/catchup

name: catchup
description: 'Use when the human returns after a gap, cannot follow the project, asks what happened, or wants a visual HTML recap page. Not for onboarding: use onboard. Not for handoff: use handoff.'
disable-model-invocation: true

Catchup

Contract

| Field | Bound contract | |---|---| | Trigger | The human returns after a gap, says they can't follow the project, asks what happened or what a term means, faces a decision with a stale mental model, or asks for a visual recap page of the project. | | Authority | Reversible local: mode visual writes only the recap page under `<project-root>/diagrams/`; mode briefing writes nothing; rollback is deleting the written file. No remote mutation. | | Side effect | Mode briefing: none; it briefs, it does not act. Mode visual: writes the 8-section recap page to the diagrams directory and opens it. | | Done | Mode briefing: a cold-read of the briefing requires no pre-gap memory or unglossed coined term to parse; needs-you items are each actionable without opening another file; every claim has a checkable source; it fits on a screen with expansion offered rather than delivered. Mode visual: a returning developer can rebuild the mental model from the page, and next steps derive only from evidence. |

Inputs

• Mode: `briefing` (default) or `visual`.
• The project working directory or project root path, inferred from the current repository when not supplied. Required for mode visual.
• The human's last touch point (their last message, judgment, or commit) for mode briefing; inferred from session history or the most recent commit when not supplied.
• Branch name for mode visual. Optional; defaults to the current VCS branch or HEAD.

Procedure

Mode briefing (default):

1. Read only live state: recent file mtimes, git log and diffs, plan and state docs, task boards, and re0-memo notes. Never brief from conversation memory alone; that memory may have drifted. **Done when:** live state is read from the project, not from conversation memory. 2. Anchor on the human's last touch (their last message, judgment, or commit). Everything after that point is the delta; everything before it is assumed known and stays out. **Done when:** the last touch point is identified and the delta boundary is set. 3. Compose in decision order, not chronological order:

• Needs you: decisions, judgments, or inputs only the human can give, each self-contained enough to act on without opening another file.
• Changed while you were away: outcomes, not process. Prefer "The plan's scoring rule was replaced" to "I ran three analysis passes."
• New words: every term coined or repurposed since their last touch, one line each, with where it lives. Skip terms they already used themselves.

Done when: the three sections are composed in decision order. 4. Gloss on first use: any project-specific term appearing in the briefing gets an inline plain-language aside at its first occurrence, even if a glossary section follows. **Done when:** every project-specific term is glossed at first use. 5. Keep the default short (a screen or less). End with drill-down offers per section, not with everything expanded. **Done when:** the briefing fits on a screen with drill-down offers, not full expansion. 6. Cold-read the briefing for pre-gap memory dependence or unglossed coined terms; confirm each needs-you item is actionable without opening another file; confirm every claim has a checkable source (file, commit, or artifact path). **Done when:** the cold-read passes with no pre-gap memory dependence, no unglossed terms, actionable needs-you items, and sourced claims.

Mode visual:

1. Confirm the project root exists and is readable; stop and report when it is not. **Done when:** the project root is confirmed readable. 2. Detect the VCS type (git or hg) and read the current branch name. **Done when:** the VCS type and branch name are determined. 3. Walk the project tree. Identify the file kinds the 8 sections need: config files, source entry points, dependency declarations, test files, documentation files, build artifacts directory, and module or package roots. **Done when:** every file kind is identified. 4. Gather the content for each of the 8 sections:

• Section 1 (Project name and branch): project directory name and current branch or commit hash.
• Section 2 (Config files): config files found (e.g., package.json, Cargo.toml, pyproject.toml, go.mod, Makefile, Dockerfile, .env.example, .editorconfig).
• Section 3 (Source entry points): main source files (e.g., src/index, main, index, app, lib, __main__).
• Section 4 (Module structure): directory tree one level deep showing the package/module layout.
• Section 5 (Dependencies): dependency declaration files and key packages (e.g., requirements.txt, package-lock.json, yarn.lock, Cargo.lock, go.sum).
• Section 6 (Test files): test files and test directory structure.
• Section 7 (Documentation): README, CONTRIBUTING, docs/ directory.
• Section 8 (Build and deploy): build scripts, CI configs, Dockerfiles, deployment configs.

**Done when:** content is gathered for all 8 sections. 5. Compose a self-contained single-file HTML page with all 8 sections rendered, inline CSS, and no external resources. **Done when:** the HTML page is composed with all 8 sections. 6. Write the page to `<project-root>/diagrams/project-recap.html`, creating `diagrams/` when it does not exist. **Done when:** the page is written to the target path. 7. Open the file in the default browser or file viewer. **Done when:** the file is opened or the open failure is reported.

Failure and recovery

• No live state found (briefing): if the working directory has no readable git history, plan docs, or task artifacts, report that the project state is unreadable and name what was checked. Do not fabricate a briefing from memory.
• Last touch point unidentifiable (briefing): state the assumption used (e.g., most recent commit) and p