| 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:
- Changes and value — three sentences a non-engineer understands, plus a table or list: what was done, what it affects, versus the baseline
- Key decisions (with what was rejected) — the 3–5 that matter; one line decision + one line why the alternative lost
- Risks and mitigations — known risks, applied mitigations, watch items
- Problems solved — key pre-existing issues closed along the way (from reports + deviations)
- Needs approval / attention — deviations still awaiting maintainer confirmation; open issue-handoff items (deferred, non-blocking); security-relevant decisions restated
- 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
