status-progression_skill

Overview

This skill guides role transitions for MCP WorkItems by inspecting current role, gate status, required notes, and selecting the correct trigger for advance_item. It helps identify the target item, fill any required notes, and execute start/complete/block/resume/cancel transitions while reporting cascades and unblocked items. Use it when you want to advance, unblock, cancel, or check why an item cannot move.

How this skill works

The skill first resolves which item to act on: a UUID is used directly, a text fragment triggers a search, and ambiguous results prompt a choice. It calls get_context to render a concise status card showing role, gate status, missing notes, guidance, and expected next trigger. If required notes block the transition, it assists in upserting notes (manage_notes) using guidancePointer or asks the user for content, then re-checks the gate before calling advance_item with the chosen trigger. Finally it parses the advance response to report role changes, cascade events, unblocked items, and next-phase expected notes.

When to use it

• When you say: "advance this item", "move to work", or "start this task".
• When you need to know "what's the next status" or "why can't I advance".
• When you must unblock work or identify blockers for an item.
• When you want to pause or resume with block/resume.
• When you need to cancel or force-complete an item.

Best practices

• Provide a UUID when possible to avoid ambiguous searches.
• If search returns multiple hits, select the exact item before proceeding.
• Always call get_context before advance_item to show missing notes and guidance.
• Use guidancePointer to populate required notes; re-check get_context after upserting notes.
• Use complete to jump to terminal only after filling all required notes across phases.
• Use block/resume pair for pausing so resume returns to the exact previous role.

Example use cases

• Start a planned item: search by title → get_context shows gate open → advance_item(trigger="start").
• Unblock an item: get_context shows missing notes → upsert notes using guidance → re-check → advance_item.
• Pause work: advance_item(trigger="block") to save previousRole, later advance_item(trigger="resume") to return.
• Skip review: advance_item(trigger="complete") after filling all required notes across phases.
• Cancel an item immediately: advance_item(trigger="cancel") — gates are not enforced.