Hand off agent sessions with decision logs (free sample)

This chat is getting long. Write HANDOFF.md: goal right now, what was done, open tasks in order, files changed, traps.
Update DECISIONS.md and BLOCKERS.md. Keep it under one screen.

A fresh session with the reasoning beats a slow one with everything.

# Hand off agent sessions with decision logs (free sample)

A free sample from Vibe Coding with AI Agents by PaperChaseWebb. Written for Claude Code, Codex and Claude.

Long agent chats get slow, expensive and forgetful. A new chat is fast but starts with no idea why the code looks the way it does. Two small files and one skill fix most of that. The idea comes from builders in our October 2026 research, including the author of the Kronograf watch firmware (u/cyberdinn on r/ClaudeAI), who kept a decision log and a blocker log so a fresh session could pick up the reasoning, not just the code.

## The rule

Add this to AGENTS.md or CLAUDE.md:

```text
Read DECISIONS.md and BLOCKERS.md before starting. Before you stop, add any new decision with its reason, and any failure with what you tried. When the chat gets long, write HANDOFF.md so a new session can continue.
```

## DECISIONS.md

```markdown
## D[n]. [Short title] ([date])
- Choice: [what we did]
- Why: [the reason, with the measurement if there was one]
- Rejected: [what else we tried]
```

## BLOCKERS.md

```markdown
## B[n]. [Symptom] ([date], open or solved)
- Seen: [exact error or behavior]
- Tried: [each attempt and result]
- Next: [what to try next, or the fix]
```

## The handoff-writer skill

Save as `.claude/skills/handoff-writer/SKILL.md` (Claude Code) or paste into AGENTS.md (Codex).

```markdown
---
name: handoff-writer
description: Use when a session is long, slow or about to end, so a fresh session can contin