catch-up

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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](#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:

```bash
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](#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:

From petekp/claude-code-setup, MIT.

More from petekp/claude-code-setup