# Catchup

> Rebuild working context fast after /clear or a fresh session — reads the handoff note and the branch's changes, then summarizes where work stands. Add `handoff` to write the note before stopping.

- Skill: `poshan0126/catchup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add poshan0126/catchup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poshan0126/catchup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: poshan0126 (https://skillmd.com/u/poshan0126)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/poshan0126/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:

```markdown
# 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.