Session handoff artifact: carry all in-flight tasks across /clear

[palonsorodriguez]

Problem

After /clear, /gsd:resume-work only reconstructs what's in files:

• STATE.md → current phase, last activity
• Git status → uncommitted changes
• Phase directories → PLAN without SUMMARY = incomplete

That's structural state — what's done or not done. It has no memory of what was in progress when you stopped:

• What you were about to do next
• Which tasks were deferred by choice vs blocked by circumstance
• Which steps require a human action (MCP Inspector, LibreChat, approvals)
• Which background processes were running

The result: users write their own handoff notes at the end of every session and paste them into the next one before /clear — otherwise that context is gone. Without the paste, /gsd:resume-work produces a generic "what do you want to do?" with no awareness of what was actually pending. Only after pasting does Claude have enough context to produce a useful, specific picture of what's blocking.

This is a workaround for a missing first-class feature.

Root cause

/gsd:pause-work exists but writes prose into STATE.md. It is not a structured artifact that /gsd:resume-work actively reads and acts on. The handoff lives in the user's head, not in the project.

Additionally, /gsd:resume-work checks for SUMMARY existence but never inspects SUMMARY content — so it misses cases like a SUMMARY frontmatter claiming requirements-completed: [VALID-01, VALID-02, VALID-03] while the body still has [To be filled in Task N — human checkpoint] placeholders. That's a false positive the workflow silently accepts.

What good looks like

In a recent session, I pasted handoff notes manually before /clear. Claude synthesized them against actual file state — and caught a discrepancy: phase frontmatter claimed requirements-completed but the body still had [To be filled in Task N — human checkpoint] placeholders. The result was this:

Priority	Item	Status
🔴	Phase 134 Task 2 — MCP Inspector: verify 118 tools, run search_documentation	PENDING (human)
🔴	Phase 134 Task 3 — LibreChat: test search_documentation, suggest_runbook, vm_list, host_list	PENDING (human)
🟡	Uncommitted changes — docker-compose --daemon removal + template text fixes	Needs /gsd:quick
🟠	Quick task — deferred todo documentation per GSD workflow	Deferred
🟠	MCP Tool Ordering — investigate alphabetic/usage-based ordering	Deferred
✅	Source type dropdown fix	Done (commit adcd4609)
✅	Model config update	Done (commit f77a08c1)

That's immediately actionable. Without the paste, the session started with a generic "what do you want to do?" — none of the blocking items were visible.

Proposed solution

/gsd:pause-work should write a HANDOFF.md — a structured artifact capturing everything that was live at pause time:

# .planning/HANDOFF.md
paused_at: "2026-03-04T14:00:00Z"
session_note: "v2.4 validation blocked on human checkpoints"

in_flight:
  - status: blocking       # gates milestone/phase close — must do first
    item: "Phase 134 Task 2 — MCP Inspector: verify 118 tools, run search_documentation"
    context: "VALID-02 required before v2.4 milestone closes"

  - status: blocking
    item: "Phase 134 Task 3 — LibreChat: test search_documentation, suggest_runbook, vm_list, host_list"
    context: "VALID-03 required before v2.4 milestone closes"

  - status: uncommitted    # code changed, no GSD backing
    item: "docker-compose flag removal + template text fixes"

  - status: deferred       # conscious choice, not forgotten
    item: "MCP tool ordering investigation"

  - status: background     # running process, no action needed
    item: "background-ingestion-job (~30h ETA)"

/gsd:resume-work should read HANDOFF.md as a first-class source alongside STATE.md and git — cross-referencing claimed statuses against actual file state, flagging contradictions, and presenting everything in a single ranked view.

The priority table is just presentation on top of a complete carry-over. The real feature is that nothing gets dropped — not the blocking items, not the deferred ones, not the background jobs.

What changes

Component	Today	With this feature
/gsd:pause-work	Writes prose to STATE.md	Writes structured HANDOFF.md
/gsd:resume-work	Reads files + git only	Also reads + cross-references HANDOFF.md
After /clear	Context lost unless user pastes manually	Full in-flight state restored automatically
SUMMARY inspection	Checks existence only	Inspects body for [pending] placeholders

Outcome

The manual paste ritual becomes unnecessary. Every session starts with a complete, specific picture of what was pending — not a generic prompt asking where to begin.