Agent Session Handoff Brief with Resume Checklist and Verified State

Makes Claude Code produce a handoff file capturing goal, verified repo state, decisions, blockers, and exact resume commands so another engineer or agent session can continue without rework. Use it before ending a long task.

You get: Working code with an explanation

More like this

The prompt

agent-session-handoff-brief-with-resume-checklist-and-verified-state.md
Role: You are a technical project handoff writer operating in Claude Code inside {repo_path}. You may read files and run read-only commands, and you may create one file: {handoff_file_path}.

Context: Work on {task_name} is pausing. The next person or agent session will have none of this conversation's context. I must decide whether the work can be safely resumed, reassigned, or merged, and what to do first.

Task: Inspect the actual repository state and write a handoff brief that separates what is verified from what is claimed or assumed.

Inputs:
- Task name and goal: {task_name}
- Original requirements or ticket: {requirements}
- Branch name: {branch_name}
- Test, lint, and build commands: {test_command}
- Known blockers or open questions from the user: {known_blockers}
- Intended audience (human engineer, another agent, or both): {audience}

Constraints:
- Create or overwrite only {handoff_file_path}. Do not change any other file, stage changes, or commit.
- Derive repo state from git status, git diff --stat, git log, and file reads, not from memory of the conversation. If memory and repo state disagree, report the discrepancy.
- Never write that something works unless you ran the check in this session and can quote the result. Label everything else Unverified.
- Do not include secrets, tokens, or private data. Reference environment variable names only.
- Keep the brief under 150 lines, with a scannable structure.

Workflow:
1. Run git status, git branch, git log -n 10 --oneline, and git diff --stat to capture the real state.
2. Run the test, lint, and build commands and record results, including failures.
3. Compare completed work against {requirements} item by item.
4. List decisions made with rationale, plus alternatives rejected.
5. List blockers, risks, and missing information, with who or what can resolve each.
6. Write exact next steps ordered by priority, each with a command or file to open first.
7. Write the file, then re-read it to validate against the acceptance criteria.

Output format (the file content, and also a short summary in chat):
1. Goal and decision supported
2. Current state (branch, last commit, uncommitted changes, test and lint and build status)
3. Requirements checklist (requirement | status: Done, Partial, Not started | evidence)
4. Decisions log (decision | rationale | alternatives rejected)
5. Blockers and open questions (item | owner | impact)
6. Assumptions and Unverified claims
7. Resume steps (numbered, with exact commands)
8. Files of interest (path | why it matters)

Acceptance criteria:
- A new session can resume using only the handoff file and the repository.
- Every Done status cites evidence such as a test, commit, or file.
- Test and build results are copied from actual runs, with failures included.
- No secrets appear, and only the handoff file was created or changed.

Quality checks:
- Re-run git status after writing and confirm only the handoff file is new or modified by you.
- Check that every command in the resume steps is valid in this repo.
- Confirm the Unverified list is non-empty only if there are real unknowns, and not padded.
- Confirm that requirements from the ticket are not silently dropped.

Tips and common edits

Run at the end of a session or before switching agents. Choose a handoff path that is gitignored or intended for commit, such as docs/handoff/. Start the next session by asking Claude Code to read the file and then verify the first resume step.

Questions about this prompt

Characterization-Test-Backed Refactor with Incremental Commits

Guides Claude Code to refactor a module safely by first pinning current behavior with characterization tests, then making small, reversible commits. Helps you decide whether the refactor preserved behavior and is worth merging.

Claude Code Repo Recon and Implementation Plan for a New Feature

Has Claude Code inspect a repository read-only and produce an evidence-based implementation plan with file-level changes, tests, risks, and open questions. Use it to decide whether to start, split, or clarify a feature before any code is written.

Pre-Merge Self-Review of a Git Diff: Correctness, Security, and Test Gaps

Has Claude Code review a branch diff like a skeptical maintainer, producing severity-ranked findings with evidence and a clear merge, fix, or block recommendation. Use it before opening or approving a pull request.

Reproduce-First Bug Fix: Failing Test, Minimal Patch, and Regression Proof

Directs Claude Code to reproduce a reported bug with a failing test, apply the smallest fix, and prove the fix with command output. Use it to decide whether a bug is fixed and safe to merge.

Session Handoff Note for a Fresh Claude Code Session

Writes a verified handoff file covering changes, decisions, open issues and next steps so a new Claude Code session can continue without re-reading the whole history.

Typed Phase Handoff Contracts and Validator for Multi-Agent Pipelines

Has Claude Code define schema-based handoff contracts between agent phases, generate a validator, and add contract tests. Supports the decision of which phase boundaries need strict contracts versus lightweight checks.

Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.

Claude Code Behavior-Preserving Refactor with Characterization Tests and Staged Commits

Guides Claude Code to refactor a module safely by first pinning current behavior with characterization tests, then applying small reversible steps with verification after each. Delivers a diff, risk register, and rollback plan.

Claude Code Feature Implementation Plan and Build from a Ticket with Repo Convention Discovery

Has Claude Code investigate how similar features are built in the repository, produce an implementation plan with acceptance tests, then implement it in verified increments. Surfaces risks, open questions, and next actions before and after coding.

Claude Code Hook Writer: Auto-Run Lint, Typecheck or Tests After Edits

Produces a PostToolUse hook entry for settings.json, the script it calls and a concrete procedure to test that the check runs after file edits.