Catchup

Catchup

Onboarding skill that produces a GUIDE.md at the repository root so a new or returning contributor can understand the project's history, current state, and how to resume work.

When to Use

• A contributor joins the repository for the first time
• A contributor returns after a long absence
• You want a single human-readable snapshot of "what has been happening here"

When NOT to Use

• You need a single focused answer (use /feature planning phases or direct research instead)
• You want to capture the current session for later (use /checkpointing)
• You want running design history (use /design-tracker or read DESIGN.md directly)

Full skill routing: AGENTS.md section "Routing Policy".

Workflow

Phase 1: COLLECT (collect_repo_state.py)
  Run the collector script -> single JSON of every dataset the template needs
    |
Phase 2: SYNTHESIZE (Claude Lead)
  Turn that JSON into per-section prose — the judgment step
    |
Phase 3: ASSEMBLE (write_guide.py)
  Stamp, order, validate, and write GUIDE.md under the Writer Safety Contract

Phase 1: COLLECT (via collect_repo_state.py)

python3 .claude/skills/catchup/collect_repo_state.py

Optional flags: --since "30 days ago" (recent-work window, passed to git), --max-commits 100, --claude-home DIR (Agent Teams data root), --project-root DIR.

Exit codes: 0 ok · 1 bad arguments · 2 not a git repository, or a SKILL.md/agent frontmatter that yields neither a name nor a description · 3 a git subcommand failed inside a real repository. The payload always carries top-level ok and errors; check those rather than assuming exit 0.

Degradation is named, never silent: an absent file is {"present": false}, an unreadable one carries an error, and a failed git subcommand is null plus an entry in git.errors — distinct from [], which means genuinely empty.

Top-level JSON keys:

• git — log, branches, status, stash, diffstat, recent_stat, current_branch, errors.
• identity — README.md, AGENTS.md, pyproject.toml presence + first line, plus identity.state with main_agent, current_project, current_feature, current_bug_fix read from .claude/STATE.md.
• rules — {present, items[{file, first_line}]}.
• skills — {present, items[{name, short_description, file}], frontmatter_errors}.
• agents — {present, items[{name, specialization, model, file}], frontmatter_errors}.
• docs — design{present, placeholder, key_decisions[]}, research, libraries.
• env — manifests, scripts (from pyproject.toml), commands (each with the source file it was quoted from), errors.
• checkpoints — newest 5 (file + first_line: the frontmatter summary, else its slug, else the first non-empty body line — never the --- fence).
• agent_teams — sessions[{name, members, tasks_total, tasks_completed}] and in-repo work_logs.
• cli_tools — recent consultations for every tool, each tagged with tool, plus skipped_lines.

Feed the emitted JSON to Phase 2 as its sole input. For very large repos hand it to general-purpose-opus for the thematic grouping.

Phase 2: SYNTHESIZE (Claude Lead)

Turn the collected JSON into one markdown body per section of references/guide-template.md. Do not re-read the source files; the collector now gathers every dataset the template asks for, so re-reading only costs context.

This phase is judgment and stays here: grouping commits into 3–7 themes, ranking the top design decisions, and deciding which optional sections are worth a reader's time have more than one defensible answer. write_guide.py deliberately takes the prose as input rather than generating it.

Omit a section entirely when its source data is absent. Never leave a {placeholder} — Phase 3 rejects them.

Write the bodies to a JSON file keyed by the section ids in references/guide-template.md:

{
  "what_is_this_project": "- **Purpose**: ...",
  "recent_work": "- ...",
  "capabilities": "### Slash commands\n\n| Command | Purpose |\n|---|---|\n...",
  "resume_work": "- **Environment setup**: `uv sync`"
}