handoff-discipline · diff
git:20260502.944fc2a to git:20260606.1256818
60 added, 21 removed. Audit A to A.
---
name: handoff-discipline
- description: "Use when completing a task or running out of context limit. Ensures the next session or human engineer has exactly what they need to resume work instantly."
+ description: Use when ending a session, handing a task back to the user, or approaching the context limit with work unfinished -- the next session or engineer must be able to resume the work instantly.
---
- # Handoff Discipline
+ ## Purpose
- When ending a session, handing a task back to the user, or preparing to swap to a new context window, you must leave a clean paper trail.
+ When ending a session, handing a task back to the user, or preparing to swap to a new context window, you must leave a clean paper trail — exactly what the next session or human engineer needs to resume work instantly.
- ## The Handoff Rules
+ ## When to Use
- 1. **State the End Condition**: Explain exactly why you are stopping (e.g., "Task complete", "Blocked on PR", "Context window too large").
- 2. **Leave a Breadcrumb**: If the task is incomplete, summarize the last successful step, the current failing step, and the *exact next command* to run.
- 3. **Commit or Stash**: Ensure the working directory is clean. Either commit the work, tell the user to commit, or stash it. Do not leave unverified messy state.
- 4. **Link the Work**: Provide file paths to the modified files or generated artifacts so the next agent/user doesn't have to search for them.
+ - A task ends (complete or not) and someone else picks it up next
+ - The context window is nearly full mid-task
+ - Work is blocked and must pause on an external dependency
- ## The Handoff Summary Format
- When creating a handoff summary file (e.g., `handoff.md`), use this exact structure:
+ ## Inputs
- ```markdown
- ### 1. Goal
- [1-2 sentences on what we were trying to do]
+ - The session's actual state: what ran, what passed, what is mid-flight
+ - The repo's working-tree status
- ### 2. State
- - ✅ Completed: [What works]
- - 🚧 In Progress: [What is broken or partial]
- - 🛑 Blockers: [What stopped us]
+ ## Workflow
- ### 3. Next Steps
- 1. Run `npm test ...`
- 2. Fix the error in `src/foo.ts` around line X.
- ```
+ 1. **State the end condition.** Explain exactly why you are stopping (e.g., "Task complete", "Blocked on PR", "Context window too large").
+
+ 2. **Leave a breadcrumb.** If the task is incomplete, summarize the last successful step, the current failing step, and the *exact next command* to run.
+
+ 3. **Commit or stash.** Ensure the working directory is clean. Either commit the work, tell the user to commit, or stash it. Do not leave unverified messy state:
+
+ ```bash
+ git status --short # what is uncommitted?
+ git stash push -m "handoff: <task>" # if not committing
+ ```
+
+ 4. **Link the work.** Provide file paths to the modified files or generated artifacts so the next agent/user doesn't have to search for them.
+
+ 5. **Write the handoff summary** (a handoff markdown file, or the final message) using this exact structure:
+
+ ```markdown
+ ### 1. Goal
+ [1-2 sentences on what we were trying to do]
+
+ ### 2. State
+ - ✅ Completed: [What works]
+ - 🚧 In Progress: [What is broken or partial]
+ - 🛑 Blockers: [What stopped us]
+
+ ### 3. Next Steps
+ 1. Run `npm test ...`
+ 2. Fix the error in `src/foo.ts` around line X.
+ ```
+
+ ## Output
+
+ - A handoff summary in the Goal / State / Next Steps format
+ - A clean, committed, or explicitly stashed working tree, with artifact paths linked
+
+ ## Verification
+
+ - [ ] End condition stated explicitly
+ - [ ] Next command is runnable verbatim by the next session — no "continue where I left off"
+ - [ ] Working tree clean, committed, or stashed — confirmed with git status, not assumed
+ - [ ] Every modified or generated file linked by path
+ - [ ] State section separates completed, in-progress, and blocked honestly
+
+ ## Failure Modes
+
+ - **Vague resumption** — "continue the refactor" instead of the exact failing step and next command.
+ - **Dirty-tree handoff** — uncommitted, unexplained changes the next session must reverse-engineer.
+ - **Completed-only reporting** — hiding the broken parts makes the handoff a trap.
+ - **Unlinked artifacts** — the next agent burns context searching for files you could have named.
+