Kanban Card Notes

Overview

Kanban cards can carry a free-text notes field (up to 8192 characters, nullable) that travels with the card through its entire lifecycle. Notes give operators a place to record observations, special handling instructions, or contextual information that cannot be captured in the card’s structured fields.

Notes are distinct from structured lifecycle data (status, location, quantity) and from print metadata. They are visible wherever the card is displayed and persist across all status transitions without being reset.

Initialization

When a card is created, the notes field is populated according to the following priority order:

1. Explicit value in the creation request — if the caller supplies a notes value, it is used as-is.
2. cardNotesDefault from the referenced Item — if the item carries a cardNotesDefault field, that value is copied to the card.
3. notes from the referenced Item — if no cardNotesDefault is present but the item has a notes field, that value is copied.
4. null — if none of the above sources provides a value, the field is left null.

This cascade ensures that standard per-item instructions are automatically propagated to every card created for that item without requiring the operator to re-enter them.

Updates

Notes can be modified after card creation by two paths:

• Standard entity update endpoint — updates the notes field as part of a full or partial card update alongside other mutable fields.
• Dedicated notes-only endpoint — a lightweight endpoint that accepts only the notes payload, allowing callers to update notes without constructing a full card update request and without risk of accidentally modifying other fields.

Both paths write through the same persistence layer and produce an auditable record of the change.

Requirements

ID	Statement
RES::KC::FR-0010	The notes field on a KanbanCard must accept up to 8192 characters of Unicode text or be null.
RES::KC::FR-0011	On card creation, the system must initialize notes using the priority cascade: explicit request value, then cardNotesDefault from the referenced item, then notes from the referenced item, then null.
RES::KC::FR-0012	The system must provide a notes-only update endpoint that modifies notes without requiring other card fields to be supplied.
RES::KC::NFR-0010	Notes must be preserved unchanged across all lifecycle status transitions.

Use Cases

Formal use case scenarios for Kanban Card Notes are planned but not yet written. They will appear under the RES::KC use case area once authored.

Related use case area: Resources — Kanban Cards.

Related

• Kanban Cards Module — implementation details for the Kanban Cards service, including entity schema, lifecycle management, and persistence.