catchup

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.