handoff

name	handoff
description	Generate a stakeholder-ready handoff document from a DevFlow plan's ledgers (PROGRESS, deviations, decisions, phase reports, final audit). First half in plain language for non-technical readers — changes and value, risks, decisions, approval points; second half a technical appendix.
argument-hint	[plan folder path]

request-devflow-plan:handoff

Generate the handoff document from the plan's ledgers. Normally used after the audit passes (an early draft after a sprint is acceptable when needed). $ARGUMENTS optionally names the plan folder. Write it in the same language as the plan documents.

Flow

Step 1 — Collect

Read from the plan folder: README.md (overview), 02-decisions.md (all D-XX), PROGRESS.md (completion state + Decision Log), implementation-notes.md §4 (deviations), the phase reports, the acceptance audit report(s), plus audit-log.md (acceptance rounds and verdicts) and issue-handoff.md (open deferred items) when present.

Step 2 — Write

Default output docs/handoff/<plan-name>-retro.md, sections in order:

1. Changes and value — three sentences a non-engineer understands, plus a table or list: what was done, what it affects, versus the baseline
2. Key decisions (with what was rejected) — the 3–5 that matter; one line decision + one line why the alternative lost
3. Risks and mitigations — known risks, applied mitigations, watch items
4. Problems solved — key pre-existing issues closed along the way (from reports + deviations)
5. Needs approval / attention — deviations still awaiting maintainer confirmation; open issue-handoff items (deferred, non-blocking); security-relevant decisions restated
6. Technical appendix — full D-XX table (condensed), open deviations, acceptance-loop history (rounds, verdicts, reports), links to every sprint's implementation plan and report, baseline vs final measurements, artifact list

Step 3 — Deliver

Write the file and give a summary with the main highlights in the conversation. No docs folder wanted? The document body itself is paste-ready for chat or a wiki.

End with the Next steps block — full copy-paste command lines (never shorthand): state that the plan's lifecycle is complete and open issue-handoff.md items (if any) wait for the next plan's recon, then print the advisory "Run /clear (or open a new session) first" followed by: /request-devflow-plan:plan — start the next piece of work (fresh interview) /request-devflow-plan:foundation — for a repo that still lacks its documentation base

Principles

• Sections 1–5: plain language, no jargon; section 6: technical
• Close with one sentence: "After this plan, is now a system that ____."

Never

• Invent decisions or content not present in the ledgers
• Hide deviations or unresolved problems