status-progression

Status Progression — Current (v3)

Guides role transitions for a WorkItem: identify the item, check gate status, fill missing notes, and advance. Handles all triggers including block, resume, and cancel.

---

Step 1: Identify the Item

Resolve $ARGUMENTS to a UUID via query_items search (operation="search", query=$ARGUMENTS, limit=5); if ambiguous, present matches via AskUserQuestion. If $ARGUMENTS is empty, ask for a UUID or title fragment.

---

Step 2: Check Current State

Once you have the item ID, call:

get_context(itemId="<item-uuid>")

Parse the response and display a status card. Use this format:

◉ "Implement authentication module"
  Role:     work
  Gate:     ⊘ blocked — 2 required notes missing
  Missing:  implementation-notes (work, required)
            session-tracking (work, required)
  Guidance: "Describe what was implemented, which files changed, and why
             the approach was chosen..."

◉ "Design API schema"
  Role:     queue
  Gate:     ✓ open — all required notes filled (or no schema)
  Next:     advance_item(trigger="start") → work

Fields to surface from get_context response:

Response Field	What to Show
item.role	Current role label
gateStatus.canAdvance	✓ open or ⊘ blocked
gateStatus.missing	List each missing note key + role
guidanceKey	Key of first unfilled required note with guidance; resolve its text via query_items(operation="schema", itemId="<uuid>") to show as "Guidance:"
noteSchema	List all schema notes with exists status

If the item has no schema (no tags matching a schema key), noteSchema will be empty and the gate is always open.

---

Step 3: Fill Missing Notes (if Gated)

If gateStatus.canAdvance = false, the item cannot advance until required notes are filled.

For each missing note, check whether its content can be inferred from the conversation context. If yes, fill it directly. If not, ask the user what to capture.