dev-handoff

Announce: "Using dev-handoff to capture session state for clean resumption."

Load shared enforcement:

Read ${CLAUDE_SKILL_DIR}/../../references/constraints/dev-common-constraints.md.

Contents

• The Iron Law of Handoff
• Handoff Facts
• Process
• Handoff Template

Session Handoff

Capture current workflow state into .planning/HANDOFF.md so a fresh session can resume exactly where this one left off. Adapted from GSD's pause-work pattern.

NO HANDOFF WITHOUT READING CURRENT STATE FIRST. This is not negotiable.

Before writing .planning/HANDOFF.md, you MUST:

1. READ .planning/SPEC.md (if exists) — understand the requirements
2. READ .planning/PLAN.md (if exists) — understand task breakdown and progress
3. READ .planning/progress.md (if exists) — the append-only ledger is the crash-safe record of which tasks are DONE; it is authoritative over PLAN.md [x] marks for "what not to redo"
4. READ .planning/ACTIVE_WORKFLOW.md (if exists) — understand current phase
5. ASSESS what is actually done vs. what remains (ledger ∪ PLAN.md [x] = done)
6. Only THEN write the handoff document

If you catch yourself writing a handoff without reading state files first, STOP.

Handoff Facts

• State files (SPEC.md, PLAN.md, ACTIVE_WORKFLOW.md) track the plan, not the session: decisions made, approaches rejected, dead ends explored, and in-flight context exist only in this conversation. A handoff that defers to the state files asserts coverage they do not have — an unverified claim presented as fact.
• Git history shows WHAT changed, not WHY or WHAT'S NEXT. "The next session can figure it out from git" hands them an archaeology task instead of a briefing — counterproductive on its own terms.
• A vague handoff ("continue task 3") costs the next session ~30 minutes of re-orientation; lost context costs roughly 10x the time a thorough handoff takes to write. Trimming the handoff to save time is anti-efficient and anti-helpful — the next session starts slower than a fresh start.

Process

Step 1: Read Current State

Read all available state files to understand where we are:

1. Read .planning/ACTIVE_WORKFLOW.md → current phase, workflow type
2. Read .planning/SPEC.md → requirements and success criteria
3. Read .planning/PLAN.md → task breakdown and approach
4. Read .planning/progress.md → append-only ledger: tasks already DONE (never redo these)
5. Scan recent git log → what's been committed
6. Check for uncommitted changes → what's in-flight

Run:

# Check workflow state
cat .planning/ACTIVE_WORKFLOW.md 2>/dev/null || echo "No active workflow"

# Completed-task ledger (crash-safe record of what's done)
cat .planning/progress.md 2>/dev/null || echo "No progress ledger yet"

# Check for uncommitted work
git status --short 2>/dev/null

# Recent commits in this session
git log --oneline -10 2>/dev/null

Description: dev-handoff: read current workflow and git state

Step 2: Assess Progress

From the state files and git history, determine:

• Current phase (from ACTIVE_WORKFLOW.md)
• Which tasks are complete (from .planning/progress.md ledger ∪ PLAN.md [x] ∪ git history — the ledger is authoritative for "do not redo")
• Which task is in progress (from uncommitted changes)
• Decisions made during this session (from session context)
• Blockers encountered (from session context)

Step 3: Write Handoff Document

Write .planning/HANDOFF.md using the template below. Every field is mandatory.

Write as if briefing a colleague who has never seen this project. Include:

• The specific file you were editing and why
• The approach you chose and alternatives you rejected
• Any gotchas or surprises discovered during this session
• The EXACT next action (not "continue working" — what specifically to do first)

Step 4: Verify Handoff

After writing, verify the handoff is complete:

1. IDENTIFY: .planning/HANDOFF.md exists
2. READ: Re-read the handoff document
3. VERIFY: Contains all sections (Current State, Completed Work, Remaining Work, Decisions, Next Action)
4. VERIFY: "Next Action" is specific enough to start immediately
5. VERIFY: Frontmatter phase/task match ACTIVE_WORKFLOW.md

If any section is empty or vague, fix it before confirming handoff.

Handoff Template

---
phase: [current phase number]
phase_name: [brainstorm|explore|clarify|design|implement|review|verify]
task: [current task number, 0 if between tasks]
total_tasks: [N from PLAN.md, 0 if no plan yet]
status: paused
last_updated: [ISO 8601 timestamp]
---
# Session Handoff

## Current State
[Where exactly we are — the immediate context a new session needs.
Include: current file being edited, current test being written,
current phase gate status. Be specific.]

## Completed Work
- [x] Task 1: [name] — Done ([brief note on what was done])
- [x] Task 2: [name] — Done
- [ ] Task 3: [name] — In progress ([what's done, what's not])

## Remaining Work
- Task 3: [what specifically remains]
- Task 4: [name] — Not started
- Task 5: [name] — Not started

## Decisions Made
- [Decision]: [what was decided and WHY]
- [Decision]: [what was decided and WHY]

## Rejected Approaches
- [Approach]: [why it was rejected — saves the next session from re-exploring dead ends]

## Blockers
- [Blocker]: [status/workaround found]
- (none) — if no blockers

## Uncommitted Changes
- [file]: [what was changed and why]
- (none) — if all work is committed

## Next Action
Start with: [specific first action when resuming — not "continue task 3" but
"run pytest tests/test_auth.py to verify the token refresh logic, then implement
the error handling in src/auth.py:45"]

Completion

Checkpoint type: human-verify (handoff completeness is machine-verifiable)

After writing and verifying .planning/HANDOFF.md:

Announce: "Session handoff saved to .planning/HANDOFF.md. Next session will detect it automatically and offer to resume."

Report to user:

Handoff saved:
- Phase: [phase_name]
- Task: [N] of [total]
- Next action: [one-line summary]

Resume by starting /dev in this project — it will detect the handoff.