What should an AI coding handoff include?

It should include current goal, changed files, git diff, decisions, failed attempts, known constraints, verification state, and the next smallest action.

What should an AI coding handoff leave out?

Leave out raw transcript history, abandoned branches, vague reasoning, and anything that does not affect the next decision.

Is HANDOFF.md better than plan.md?

They serve different jobs. plan.md describes intent and tasks. HANDOFF.md describes current working state for the next session.

A good AI coding handoff is a forward brief, not a transcript.

Use this structure when you restart a chat, switch tools, or need another AI agent to continue without inheriting stale context.

Short version: a good AI coding handoff file is a forward brief. It tells the next agent what is true, what changed, what failed, what not to touch, and what to do next.

HANDOFF.md vs plan.md vs transcript.

A transcript is history. A plan file is intent. A handoff file is continuity. It should let a fresh AI session continue the work without rereading every file or repeating dead branches.

The handoff format that works.

Goal. One sentence describing the work.

Current state. What is done, partial, and untouched.

Files that matter. Touched files, read files, and likely next files.

Decisions. What was chosen and why.

Failed attempts. Dead ends tied to constraints, not the whole reasoning trail.

Verification. Tests, commands, screenshots, manual checks, and failures.

Next action. The single smallest next move.

Make verification reproducible.

Include the command, working directory, observed result and commit or diff covered by each important check. A test passed before the latest edit is historical evidence, not verification of the current tree. State when a check was not run or requires unavailable credentials.

For rejected approaches, record the observed error and what must change before retrying. Review repository visibility before committing internal URLs or logs; keep secrets out. A handoff narrows the next action without authorizing destructive operations.

What to leave out.

Drop raw transcript history, abandoned branches that do not matter, broad model opinions, and reasoning that did not change a decision. Noise makes the next agent worse.

Example skeleton.

# HANDOFF.md

## Goal
Finish the checkout refactor without changing billing rules.

## Verified state
- Files changed: ...
- Tests passing: ...
- Tests failing: ...

## Decisions
- Use X because ...

## Failed attempts / do not retry
- Tried Y; failed because ...

## Next action
Run ... and fix ...

Where ShardStitch improves the file.

Manually maintained handoff files work if you remember to update them. ShardStitch helps when you forget, the session dies, or you need a format for another tool. It reads disk truth and builds a lean continuation packet automatically.

FAQ.

Should the handoff live in the repo?

Often yes. Repo-native files are easy to grep, diff, and review. The risk is forgetting to update them before the session dies.

Should I include failed attempts?

Yes, but only the failed attempts that prevent repeated work. If a dead end is not tied to a constraint, it is usually noise.

Generate handoffs with ShardStitch