handoff-report

# Handoff Report Structure any substantive report so the reader can act on the first paragraph and audit the rest. Full doctrine: `docs/agent-craft.md` §5 and §7. ## Order 1. **Outcome first.** The first sentence answers what the reader would ask for if they said "just the TLDR": what happened, what was found, or what is blocked. Not the journey, not the setup. 2. **Failures and scope changes in the first block.** A failed check, a skipped step, a scope change, an error worked around — these go up front even when embarrassing, never mid-report. The most informative event is the one you are tempted to smooth over. 3. **Reasoning, auditable.** Evidence pointers with every load-bearing statement: `file.ts:line`, the log excerpt, the measurement, the command that produced the number. Trust should rest on checkable references, not on tone. 4. **Residual risk last, explicitly.** What remains unverified, what to check next, what would invalidate the conclusion. If there is genuinely no residual risk, say that — the reader cannot distinguish "no risk" from "risk section omitted". ## Labeling - Every load-bearing statement is sortable by the reader into **observed** (ran it, read it, saw it) / **derived** (follows from observations by stated reasoning) / **assumed** (plausible, unverified) — without asking you. - Use cheap explicit markers: "verified:", "inferred from X:", "assumption:". Never let sentence confidence do the labeling; fluent prose reads as fact regardless of bin. ...