Catchup
Rebuild what you were doing after a cleared chat, compacted context, or a new session in an existing branch or worktree—without writing files or changing git state.
Overview
Catchup is a journey-wide agent skill that reconstructs repo, plan, and workflow context in read-only mode whenever a solo builder resumes after `/clear`, compaction, or an unknown worktree state.
Install
npx skills add https://github.com/camacho/ai-skills --skill catchupWhat is this skill?
- Strictly read-only ritual—no file edits, branches, or write commands
- Parallel gather: git log/status/worktrees, `.branch-context.md`, `MEMORY.md`, `HANDOFF.md`, open plans
- Optional Basic Memory MCP search and authenticated `gh` PR/issue lists when available
- Structured synthesis template with sections omitted when empty
- Designed for `/clear`, `/compact`, resume, and unknown worktree context
- 20-commit git log window
- up to 15 open issues when `gh` is authenticated
Adoption & trust: 557 installs on skills.sh; 1 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You cleared or compacted the agent session and no longer know which branch, plan file, validation round, or open PR you were on.
Who is it for?
Multi-session agent workflows with `.branch-context.md`, `ai-workspace/plans/`, and optional `gh`/Basic Memory already set up on the machine.
Skip if: First-time repo setup, greenfield brainstorming, or sessions where you want the agent to commit, branch, or edit files as part of catch-up.
When should I use this skill?
Use after /clear, /compact, session resume, or context loss; when branch context is stale or unknown; when starting work in an existing worktree.
What do I get? / Deliverables
You get a synthesized status briefing from git, branch metadata, memory, handoff, and plans so you can pick the next skill or task without mutating the repository.
- Structured context briefing (read-only synthesis)
- Omitted-empty sections status report
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
You open a feature worktree Monday and run catchup to see the open plan chunk and validation round before implementing.
After compacting mid-review, catchup pulls open PRs via `gh` and branch review counters so you do not re-audit the wrong commit.
You return to a hotfix branch and need MEMORY.md blockers and recent commits without touching production configs.
A stale chat on a spike branch—catchup confirms whether a plan file is still active versus `.done.md`.
How it compares
Use instead of manually re-pasting specs or re-asking "what were we doing?"—it is a read-only ritual, not a planning or coding skill.
Common Questions / FAQ
Who is catchup for?
Solo and indie builders who run long agent sessions on real git repos and regularly hit context limits, worktrees, or handoffs between chats.
When should I use catchup?
After `/clear` or `/compact`, on session resume, when branch context is stale, at the start of work in an existing worktree, during Build when jumping back to a feature branch, during Ship before review work, or in Operate when resuming incident or iteration threads.
Is catchup safe to install?
The skill itself only instructs read-only git and file reads plus optional MCP/`gh` queries; review the Security Audits panel on this Prism page before installing the parent package.
SKILL.md
READMESKILL.md - Catchup
# Catchup — Context Reconstruction **This skill is strictly read-only. Do NOT edit files, create branches, or run write commands.** ## 1. Gather data (run all independent steps in parallel) - `git log --format="%h %s (%ar)" -20`, `git status`, and `git worktree list` - Read `.branch-context.md` (if exists — check CWD and worktree root). Parse YAML frontmatter: `workflow_step`, `validate_round`/`validate_max`, `review_round`/`review_max`, `plan_review_chunk`/`plan_review_total`/`plan_chunks_approved` - Read `ai-workspace/MEMORY.md` — note anything in-progress or blocking - Read `HANDOFF.md` (if exists) - List `ai-workspace/plans/` (sort by mtime, most recent first) and read the first file that does NOT end in `.done.md` or `.executed.md` - Search Basic Memory via MCP for recent entries matching the current branch name. If MCP unavailable, skip silently. - **GitHub** — check availability first: ```bash command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 ``` If authenticated, run in parallel: ```bash gh pr list --state open gh issue list --state open --limit 15 ``` If `gh` is unavailable or unauthenticated, note "GitHub CLI unavailable" and skip. Do NOT attempt to install or authenticate. ## 2. Synthesize Present findings in this format. **Omit sections where the data source was not found** (e.g., no HANDOFF.md, gh unavailable). Always show Loop state and Blockers even when empty — absence is informative: ``` Branch: <name> — <what we're building (from plan or branch-context)> Worktree: <path> (or "primary") Last commit: <hash> <message> Uncommitted: <staged/unstaged summary, or "clean"> Workflow step: <N> — <step name> (from frontmatter, or inferred) Loop state: validate <round>/<max>, review <round>/<max> Active plan: <file> — <current phase> — <next action> Blockers: <list> Open PRs: <count — titles> Open issues: <count — top 5 titles> Handoff: <detail> ``` After the summary, **surface blockers and TODO items prominently** — remaining work, failing CI, stale branches, items from memory flagged as blocking. These go above the fold, not as footnotes. ## 3. Suggest next actions Based on gathered state, suggest 2-3 concrete next actions. Examples: - "Resume building — plan X is at step 5 (Build)" - "Run /validate — implementation looks complete" - "Address blocker: [description]" - "Review open PR #N — awaiting action" - "Pick up issue #N — in-progress" End with: "What would you like to do?" ## Failure modes - **No `.branch-context.md`**: infer workflow step from git state and plan file status. Note: "No branch context — step inferred." - **No active plan**: note "No active plan." Do not search `.done.md` files. - **On `main` branch**: skip branch-context and plan lookup. Show git state, PRs, issues, and memory only. - **Basic Memory MCP unavailable**: skip silently. - **`gh` unavailable**: show "GitHub CLI unavailable — PR/issue status unknown."