petekp/catch-up

Catch Up

The person reading this has been away. While they were gone, agents (you and others) moved the project forward. They are juggling several projects like this one and do not read the code closely. Your job is to get them back in the driver's seat in under a minute: what changed, why it changed, and where their input would actually steer things.

That framing decides everything below. They cannot act on a diff or a commit list, so do not give them one. They can act on plain ideas and clear choices, so give them those.

What good looks like

• Plain English, zero jargon. Every technical term either gets translated or explained the first time it appears. If a reader who has never seen the code would stumble on a word, rewrite it. See Translating jargon.
• Altitude, not inventory. Group changes by what they mean, not by file. One idea per bullet. The headline is the thing, not the line count.
• The why is the payload. The diff says what changed; only the conversation says why. The reader steers on the why, so make sure it survives.
• Surfaces the forks. The single most useful thing you can give a steerer is the list of decisions that are still open, or were made by default and could be reversed. That is where their attention belongs.
• Honest. If something is half-done, untested, or went sideways, say so. A catch-up that hides loose ends makes steering worse, not better.

How to do it

1. Find the starting line

State the window you are summarizing, in one short phrase, so the reader knows the frame. Infer it from the conversation, in this order:

1. A previous catch-up. Scan the transcript for the last time you ran this skill (your own output, led by a window line like the ones below). If you find one, summarize only what happened after it. This is the common case when they check in repeatedly.
2. A clear milestone. A merge, a shipped PR, a finished plan, or an explicit "let's start on X" is a natural starting line. Summarize since then and name it: "Since the auth refactor merged".
3. The session start. If neither of the above is clear, summarize the whole session and say so: "This session so far".

If the transcript was compacted or you genuinely cannot tell, default to session start, say that is what you did, and lean on git (below) to recover the missing history rather than guessing.

Good window lines: "Since your last check-in", "Since we started on search", "This session so far", "Since the v2 branch merged".

2. Gather what changed

Lead with the conversation — in an agent-driven project it holds both the work and the reasoning. Then ground it against the repo so you are reporting what actually landed, not what was merely discussed:

git log --oneline -20        # what actually got committed
git diff --stat HEAD~N       # rough shape of the change (pick N from the log)
git status                   # what is still uncommitted / in flight

Use git to confirm the what and catch anything that happened off-screen. Use the conversation for the why. Do not read every file — you are after the shape of the change, not a line-by-line account. A quick look at one or two key files is fine when you need to understand an abstraction well enough to name it plainly; reading ten is a sign you have lost the altitude.

3. Keep only what helps them steer

Keep: the core moving parts that were added or reshaped (named in plain words), the approach chosen and any real alternative that was rejected, the reasoning, decisions that now lock things in, open forks, and anything surprising or risky.

Drop: file-by-file churn, line counts, formatting and lint noise, mechanical renames, and anything the reader could not act on. If you are unsure whether something belongs, ask "could they steer on this?" If not, cut it.

4. Write the briefing

Use the structure below. Scale it to how much actually changed — see Scale to the change. Drop any section that would be empty; an honest short note beats a padded template.

[Window line] (TL;DR)
<one or two plain sentences: the headline, plus how many things need them>

What changed
- <a change, in plain language, grouped by theme>
- <a knock-on effect, if it matters to them>

Why
- <the problem being solved or the reasoning behind the approach>

Your call
- <open decision>: <the tradeoff in plain terms>. <what you did by default>.

Keep each bullet tight: lead with the point in one line. Add at most one plain sentence after it, and only when a term genuinely needs unpacking for someone who has not seen the code. More than that and you have slipped from briefing into narration — cut it back, or split it into two bullets.

The Your call section is the steering payload. List real forks: things left undecided, or decided by default and easy to flip. For each, give the tradeoff in one plain sentence and say what you did in the meantime so they know the current state. If nothing needs them, say so in one line ("Nothing needs you right now.") rather than inventing a decision.

Translating jargon

This is the core move, so it is worth doing well. Name the underlying idea, not the implementation. A few examples of the translation:

| Instead of | Say | |---|---| | "Added a reducer to centralize state" | "Put all the app's 'what's true right now' bookkeeping in one place instead of scattered around" | | "Memoized the selector" | "Made a slow lookup remember its answer so it stops recomputing every time" | | "Introduced a discriminated union for the result" | "Made a result always be exactly one of a few clearly-labeled shapes, so we can't mix them up" | | "Extracted the API client into a shared module" | "Moved the code that talks to the server into one shared spot so every screen uses the same one" | | "Added optimistic updates" | "The screen now shows your change instantly and quietly fixes itself if the server disagrees" |

Two practical tells. First, if a name in your draft only means something to someone who has read the code (a class name, a file name, an internal codename), replace it with what it does. Second, write the way you would explain it out loud to a smart colleague on a different team. That voice is almost always the right altitude.

Scale to the change

The structure is a guide, not a quota. Match the output to the substance:

• Tiny change (a fix, a tweak): one or two sentences. No headers. "Fixed the bug where the export button did nothing on empty lists. Nothing needs you."
• Normal session: the full briefing, a few bullets per section.
• Big or sprawling session: still lead with one TL;DR line, then group the body by theme so it stays skimmable. Resist the urge to be comprehensive — completeness is the enemy here. Pick the handful of things that change how they would steer, and note that smaller stuff was skipped.

Voice

Short sentences, one idea each. No em dashes. Skip the AI throat-clearing ("It's worth noting that...", "delve", "robust", "leverage", "seamless"). Write like a sharp colleague catching them up between meetings, not like a release note.