# Catchup

> Get a fresh session up to speed from context.md — read the last handoff, verify it against git reality, and deliver a short briefing ending in one proposed next action. Use at the start of a session, after /clear, or when the user says "catchup", "catch up", "get up to speed", "where were we", or "what's the status". Counterpart of the handoff skill.

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

---


# catchup — resume from context.md, verify against reality

The `handoff` skill writes the session-end snapshot; this skill is the other
half: a fresh agent reads it, **checks it against the actual state of the
repo**, and briefs the user. The handoff was written in the past — treat it as
testimony, not truth.

## 1. Read the record

- `CLAUDE.md` — the house rules and registry (usually auto-loaded; skim if not).
- `context.md` — read **§0 top 3 entries fully**; skim the rest of §0 and the
  stable sections (§1+) for anything the top entries reference.
- `SPEC.md` (if present) — only the acceptance criteria and open decisions, to
  know what "done" means and what's undecided.

If `context.md` is missing or has no §0 entry: say so plainly, and offer to
reconstruct a status from `git log` + the working tree (then recommend running
handoff at session end so this doesn't happen again).

## 2. Verify against reality (read, don't trust)

```bash
git status --short            # uncommitted / untracked work
git log --oneline -8          # what actually landed
git branch --show-current     # off main?
git stash list                # parked work
git log origin/$(git branch --show-current)..HEAD --oneline 2>/dev/null  # unpushed?
```

Compare with the newest §0 entry and flag **drift** explicitly:
- Uncommitted or untracked files the entry doesn't mention.
- Commits newer than the entry's date (someone/something worked after the handoff).
- Entry says "pushed" but the branch is ahead of origin (or origin unreachable).
- Stashes the entry doesn't mention.
- Anything in `Next:` that appears to have already been done.

No drift is a finding too: "context.md matches the repo."

## 3. Brief the user (≤ ~15 lines, then stop)

```
**Where we are:** <1–2 sentences from the newest entry, in plain language>
**State:** <committed/pushed status; what was verified vs only assumed>
**Drift:** <mismatches found, or "context.md matches reality">
**Next (from handoff):** <the Next: list, updated for anything already done>
**Blocked on you:** <open questions / ⚠️ items awaiting the user, if any>

Suggested next action: <the single most sensible step>. Want me to start?
```

## Rules

- **Never start building from a catchup.** The briefing ends with one proposed
  next action and a question — the user decides. (Exception: the user's message
  already contained a work instruction alongside "catchup"; then brief first,
  work second.)
- Don't re-verify claims marked *verified* in the entry by re-running the app —
  trust the record for those; spend your skepticism on git-visible drift.
- Keep the briefing honest about the *assumed* items — they're the likely
  landmines of this session.
- Read-only: catchup changes nothing, commits nothing, writes nothing.