| name | handoff |
| description | Creates a HANDOFF.md document that captures progress, findings, and remaining work so a fresh agent can continue without context loss.
TRIGGER when: the current agent cannot complete a task and needs to pass it to a new agent, context window is nearly full, or user explicitly requests a handoff.
DO NOT TRIGGER when: the task is normal ongoing work with no agent transition needed. |
Handoff
Overview
Produce or update a single continuation document that lets a fresh agent resume work without rereading the prior session. The handoff is not a status report. It is a reboot packet.
Core principle: A fresh agent reading only this document (plus the codebase) can continue the task effectively.
When to Use
- The current agent cannot finish the task (context limit, session timeout, user handoff request).
- The user explicitly asks for a handoff, context summary, or session transfer.
- A multi-session task has reached a natural break point where continuation by a new agent is likely or planned.
When NOT to Use
- Work is ongoing with no transition needed.
- The user asks for a summary, changelog, or documentation that is not meant for a fresh agent.
- The task is trivially complete and no continuation context is useful.
- The user wants a commit message, PR description, or release notes (those have their own formats).
Contract
This skill operates under the following rules. Every invocation must satisfy all six points.
1. Trigger Conditions
See ## When to Use above.
2. Non-Trigger Conditions
See ## When NOT to Use above.
3. Output Destination
The generated handoff document is always written to:
<active-project-root>/HANDOFF.md
This is the project root of the repository or workspace the agent is working in.
Never write generated handoff output into:
- The skill directory itself or its subdirectories
- A
system-prompt-extraction/ folder (this is a known anti-pattern from an earlier version)
- Any path outside the active project root
4. Primary Audience
The only intended reader is the next fresh agent who picks up the task. Optimize for that reader:
- Prioritize current state and next steps over history. Current State appears early in the document so the next agent knows where things stand before reading details.
- Include only context the fresh agent needs to act.
- Omit session narrative, general observations, and anything the fresh agent could discover by reading the codebase.
5. Evidence Rule
Every factual claim about progress, state, or results must be backed by evidence when available:
- File paths for changed or relevant files.
- Commands that reproduce a result or verify state.
- Commit hashes for changes pushed.
- Error output for failures encountered.
When evidence is unavailable or unverified, label it explicitly:
[UNVERIFIED] for claims not yet confirmed.[UNKNOWN] for facts that could not be determined.
Never fabricate or guess missing context. A labeled gap is always better than a fabricated assertion.
6. Existing HANDOFF.md Handling
When <active-project-root>/HANDOFF.md already exists, apply this three-step decision procedure:
Step 1: Classify the existing file. Read it and determine which case applies:
| Signal | Classification | Action |
|---|
| Different task, different workstream, or task fully completed | Obsolete | Replace fully. Discard entire file. |
| Same task, same workstream, still in progress | Active continuation | Proceed to Step 2. |
| Same task but state has diverged significantly from reality | Stale continuation | Proceed to Step 2 (treat as selective salvage). |
Step 2: Evaluate each section for carry-forward. For each section in the existing file, apply this test:
Would the next agent be materially worse off if this section were missing?
Materially worse off means the section contains one of:
- An unresolved blocker or risk that is still open (not resolved in the current session).
- A key decision with rationale that the next agent might reverse without understanding why it was made.
- A failed approach or dead end the next agent would otherwise retry.
- An environment or setup detail not discoverable from the codebase alone.
If the section meets none of these criteria, discard it. Do not preserve it "just in case."
Step 3: Compose the new document. Write a fresh document from the template. For any section that passed the Step 2 test, carry its content forward into the corresponding new section. Do not create a "Legacy" or "Previous" section to dump old content. Integrate carried-forward facts into the appropriate template sections. Prefix each carried-forward item with [PRIOR] so the next agent can distinguish inherited context from facts established in the current session. Example: [PRIOR] CI pipeline requires Node 18; newer versions break a native dependency.
Rules that always apply:
- Never append the new document after the old one. This produces a confusing hybrid that forces the next agent to guess which parts are current.
- Never carry forward a section verbatim without re-evaluating it. Even if a section seems relevant, verify its facts are still accurate before including it.
- When in doubt, replace fully. A clean, smaller document is always better than a bloated one padded with uncertain legacy context.
Output Location
| Asset Type | Location | Notes |
|---|
| Template (reference structure) | ${SKILL_ROOT}/templates/HANDOFF.md | Read-only scaffold the agent uses as a guide |
| Generated output (actual handoff) | <active-project-root>/HANDOFF.md | The document the agent writes for the next agent |
The template is an asset shipped with the skill. The generated output is the handoff document the agent produces at runtime. They are separate things. Never write generated output into the template path.
Required Sections
Every generated <active-project-root>/HANDOFF.md must include these sections, in this order:
- Task - What was the agent trying to accomplish. One or two sentences.
- Current State - Where things stand right now. What is done, what is in progress, what is blocked. Lead with this.
- What Was Done - Changes made, with file paths and commit hashes where available. Not a narrative. A list.
- Key Decisions - Architectural or design choices made, and why. Only include decisions the next agent might question or reverse.
- Open Issues - Unresolved problems, known bugs, things that still need investigation. Use
[UNKNOWN] or [UNVERIFIED] tags where evidence is missing.
- Next Steps - Ordered list of concrete actions the next agent should take. Be specific: file names, command lines, test names.
- Context for Continuation - Anything else the next agent needs but cannot easily discover from the codebase. Keep this tight.
If a section would be empty, include it with a one-line note like "None at this time" rather than omitting it. The next agent needs to know the section was considered.
Supplementary sections beyond these seven (e.g., Verification Commands, Key Files, Evidence & References) are allowed when they help the next agent act. They must earn their place: omit them if they contain no information the next agent could not discover from the codebase.
Process
- Assess need. Confirm a handoff is warranted (see trigger conditions). If not, stop.
- Gather evidence. Read recent files, git log, error output, and any existing planning documents. Do not guess.
- Check for existing HANDOFF.md. If one exists, follow the three-step procedure in Contract point 6: classify the file, evaluate each section for carry-forward, then compose fresh from the template.
- Draft the document. Follow the required sections above. Current State appears early so the next agent sees the status first. Mark unknowns as
[UNKNOWN] or [UNVERIFIED]. Do not fabricate.
- Write to
<active-project-root>/HANDOFF.md. Not the skill directory. Not a subdirectory. The project root.
- Verify resumability. Read back the written file. Apply the Resumability Criteria audit: confirm all six questions (where am I, what was done, what failed, what remains, how do I verify, what don't I know) have concrete answers. Confirm every factual claim is either evidenced or tagged
[UNKNOWN]/[UNVERIFIED]. If any question is unanswered, revise before finalizing.
Common Mistakes
| Mistake | Fix |
|---|
| Writing a narrative timeline ("First I did X, then I tried Y...") | Use structured sections. The next agent needs state, not story. |
Writing to the skill directory or system-prompt-extraction/ | Always write to <active-project-root>/HANDOFF.md. |
| Appending to an existing HANDOFF.md without classifying it | Follow the three-step procedure in Contract point 6: classify, evaluate per-section, compose fresh. |
| Creating a "Legacy" or "Previous" section to dump old content | Integrate carried-forward facts into the appropriate template sections. No dumping grounds. |
| Carrying forward a section verbatim without verifying accuracy | Re-check each fact before including it. Stale facts are worse than missing facts. |
| Omitting evidence ("tests pass" without the command or output) | Include the command and a summary of the result. |
| Fabricating or guessing missing information | Tag as [UNKNOWN] or [UNVERIFIED]. Gaps are fine. Lies are not. |
| Including information the next agent can discover from the codebase | Omit it. The handoff is for continuation context, not a codebase tour. |
| Leaving out the Next Steps section | This is the most important section for the next agent. Always include it. |
| Mixing template structure with generated content | Template is read-only reference. Generated output goes to the project root. |
Resumability Criteria
A handoff document is resumable if a fresh agent reading only that document (plus the codebase) can answer all six of these questions without guessing:
| # | Question | Where in the document | Pass condition |
|---|
| 1 | Where am I? What was the last completed action? | Current State | States the last completed action explicitly. Not "we worked on X" but "file Y was edited, line Z changed, commit abc1234." |
| 2 | What was done? What changes exist in the codebase? | What Was Done | Lists every changed file with evidence (path, commit hash, or command output). No vague "refactored the module" without specifics. |
| 3 | What failed or blocked? What dead ends and blockers exist? | Open Issues + Dead Ends | Every blocker names the specific error, file, or test. Every dead end names the approach tried and why it failed. Tagged [UNKNOWN] if evidence is missing. |
| 4 | What remains? What must happen next? | Next Steps | First step is independently actionable (a specific command or file edit). Steps are ordered, not a wishlist. |
| 5 | How do I verify? Can I confirm current state before proceeding? | Verification Commands (supplementary) | At least one command the fresh agent can run to confirm the handoff accurately describes the codebase state. |
| 6 | What don't I know? Where are the gaps? | Throughout | Every information gap is tagged [UNKNOWN] or [UNVERIFIED]. No fabricated details filling gaps. |
Anti-fabrication rule: If the agent cannot determine a fact (e.g., whether a test passes, what a file contains, whether a change was committed), it must tag the gap explicitly. A handoff with five labeled unknowns is resumable. A handoff with one fabricated assertion is not.
Verification procedure: After writing the handoff, the authoring agent must perform this audit:
- Read the document back.
- For each of the six questions above, confirm the document provides a concrete answer (not a guess).
- If any question cannot be answered from the document alone, revise that section.
- Confirm every factual claim is either evidenced or tagged
[UNKNOWN]/[UNVERIFIED].
A handoff that passes this audit is resumable. One that does not is a status report, and the next agent will waste time re-discovering context.
Integration
With planning-with-files
If task_plan.md, findings.md, or progress.md exist in the project, reference their locations in the handoff. The next agent should know these files exist and can read them for deeper context.
With verification-before-completion
Before declaring the handoff complete, verify: read the file back, confirm all required sections are present, and check that every claim is evidenced or tagged.
With session recovery
When an agent starts a new session and finds <active-project-root>/HANDOFF.md, it should read that file first before examining the codebase. The handoff is the entry point for continuation.
