catchup

Two modes. $ARGUMENTS containing handoff → write the handoff note (end of session). Anything else → catch up (start of session), treating any remaining arguments as a focus area.

Catch up (default)

Rebuild context in four steps, cheapest first. Read; never modify anything.

1. Handoff note: if .claude/HANDOFF.md exists, read it first — it's the previous session's intent and beats anything inferable from git. Note its date; flag if it predates the latest commit (it may be stale).
2. Branch state — live snapshot injected below (git output as of this session's start; no need to re-run these three):

BASE=$(git merge-base HEAD origin/HEAD 2>/dev/null || echo HEAD~10)
echo "### git status (uncommitted/staged work in flight)"
git status --short 2>/dev/null || echo "(not a git repo)"
echo
echo "### git log --oneline ${BASE}..HEAD (what this branch did)"
git log --oneline "${BASE}..HEAD" 2>/dev/null || echo "(no divergence from base)"
echo
echo "### git diff --stat ${BASE}..HEAD (where the change mass is)"
git diff --stat "${BASE}..HEAD" 2>/dev/null || echo "(no diff vs base)"

3. Read the changed files — the diff hunks, not whole files. If more than ~15 files changed, read the 5 with the most churn plus anything matching the focus area, and list the rest by name.
4. Summarize in this shape, terse:

## Catchup: <branch>

**Goal** (from handoff or inferred): <one line>
**Done**: <commits/changes, 2-4 bullets>
**In flight**: <uncommitted work, or "clean">
**Next** (from handoff, or inferred): <one line>
**Watch out**: <gotchas from the handoff, if any>

If there's no handoff note and no branch divergence (fresh clone, main at origin), say so and ask what to work on instead of inventing a summary.

Handoff (when $ARGUMENTS contains handoff)

Write .claude/HANDOFF.md capturing THIS session for the next one. Keep it under 30 lines — it's a note, not a transcript:

# Handoff — <date> — <branch>

## Goal
<what this work is trying to achieve, one line>

## State
- Done: <completed + verified>
- In flight: <started, not finished — exact file/function>
- Untouched: <known remaining scope>

## Gotchas
- <what failed and why, dead ends not to repeat, surprising constraints>

## Next step
<the single concrete action to take first>

Show the note and confirm before writing. Overwrite any existing note (it described an older state). Suggest adding .claude/HANDOFF.md to .gitignore if it isn't there — it's personal session state, like CLAUDE.local.md.

Rules

• Catchup mode is strictly read-only.
• Never paste large diffs into the summary — reference file:line and characterize.
• The handoff captures decisions and dead ends, not narrative. "Tried X, broke Y, use Z instead" is the gold standard line.