---
name: catch-me-up
description: "Use for \"catch me up\", getting oriented in an unfamiliar repo, or returning after time away: module map and entry points, repo conventions, test structure, unfamiliar syntax, or what changed recently. Six exploration modes with deliberately visual output. Routes feature traces to how and decision rationale to why."
---

# Catch Me Up

Answer the recurring comprehension questions about a codebase without the user having to formulate them each session. Most sessions are comprehension, not generation; this skill freezes the questions that repeat.

The deliverable automates the question, not the understanding. Every claim cites its source so the user can check it against their own mental model: `file:line` for current code, and a commit hash, PR link, or changelog entry for history findings, whose evidence often no longer exists at any current `file:line`. Inference is labeled apart from what you read (the **align-on-intent** principle skill).

## Modes

Pick the mode or modes the ask names. A bare "catch me up" runs the orientation sweep: architecture, convention, testing, and history at survey depth.

| Mode | Level | Answers |
| --- | --- | --- |
| Architecture | global | module map, dependency direction, entry points |
| Convention | local | naming patterns, lint rules, repo-specific idioms |
| Feature trace | local | how one feature flows across modules |
| Syntax | detailed | unfamiliar constructs or API surfaces |
| Testing | detailed | test structure, fixtures, assertion patterns, how to run them |
| History | cross-cutting | recent changes, deprecations, migration context |

Routing: a feature trace is the **how** skill; invoke it. "Why is it built this way" is the **why** skill. History's what-changed belongs here (git log, merged PRs, changelogs); the motivation behind a change routes to **why**.

## Explore

Read-only. Match depth to the mode's level: global modes survey (directory trees, manifests, entry points, dependency edges), local modes read the real code of the named area, detailed modes read narrowly and completely.

When the ask names no direction, walk recent commit history for hot spots (the files and directories changing most) and weight the survey toward them. Where the churn is is where a newcomer needs the map first.

When the repo has a `CONTEXT.md` glossary, use its terms for the repo's own concepts (the **define-the-terms** principle skill). An orientation that renames the codebase's vocabulary misorients.

For a large repo or the full sweep, delegate exploration per the **guard-the-context-window** principle skill: one read-only subagent per mode on your configured how explorer model (default `sonnet`), file pointers back, no inlined dumps. A small repo or a single mode: explore in place.

For history, read `git log` since the relevant date or tag, merged PRs, the changelog, and migration or deprecation notes. Name what moved, what is deprecated, and what a returning contributor would trip on first.

## Deliver visually

Every mode's deliverable leads with structure, not prose: the module map as a tree or diagram, conventions as a table with one real example each, a feature trace as an ordered hop list with `file:line` per hop, history as a table (change, when, where, what it replaced). Prose explains the structure; it never substitutes for it.

Write the deliverable as one self-contained HTML file: a navigable page with a section per mode, saved to the OS temp directory (resolve `$TMPDIR`, `/tmp`, or `%TEMP%`) with a timestamp in the name so runs never overwrite each other. Open it with the platform opener and give the user the path. On a host that also publishes pages, publish the same page and hand over the link too. A single narrow mode answered inline may skip the file and land as markdown in the reply; the orientation sweep always gets the page. Diagram syntax the page renders (mermaid, inline SVG) beats ASCII; ASCII beats nothing.

## Close

Open the close with a **Start here** pointer: the entry point plus the first two or three files to read, in order. An orientation without a starting move leaves the user oriented and still stuck.

Then the two lines the user checks you against: what you read (files, commits, counts) and what you inferred without reading. An orientation that hides its blind spots reads as complete and is not.