Recap Current Work

Catch the user up on a session, fast, when they have lost the thread. The guiding case: the user runs many agents in parallel and, coming back to one, cannot remember what it was doing or tell whether it actually finished. A recap exists to fix that in one message, and above all to make half-done work impossible to miss. Agents tend to present a plausible summary that quietly buries the one thing that is not wrapped up; the recap's whole job is to surface it instead.

A recap is a point-in-time status pulled from real state. It looks backward and at now. It is not a forward plan (that is the dev-workflow living checklist) or a look back at process (that is a retrospective).

Two modes

Always-on end-of-turn recap. End every substantive turn with a brief recap, unprompted, so the user never has to ask just to re-orient. Keep it to the one or two workstreams the turn touched, each line carrying its status marker. This is the cheap, constant heartbeat, not the full catch-up. Skip it only for trivial conversational turns where there is nothing to track.
On-demand zero-context recap. When the user asks to recap, assume they have zero memory of the session and catch them up start to finish, efficiently. This is the full version described below.

The structural rule: group by meaning, mark status per item

Group the recap by meaning (workstream, topic, or deliverable), the units the work actually breaks into. Do not group by completion state. A "Done" section followed by a "What's left" section is the anti-pattern this skill exists to kill: it scatters each workstream across two places and hides how far along any one thing is.

Instead, put a status marker on every individual item, inside its natural group:

✅ done (verified against real state)
⏳ in progress
❌ error or failure (a failing test, a command that errored)
🛑 blocked (waiting on a decision, a credential, or something external)
⚠️ warning or caveat (a risk, a rough edge, or something you could not verify)
◻️ not started

Because every item wears its own marker, incompleteness stays loud: an ⏳, ❌, 🛑, or ◻️ jumps out mid-group when the user scans. Tag the owner inline on anything still open, (you) versus (agent), rather than splitting work into a separate to-do list.

What a zero-context recap contains

🎯 Goal, one line at the top: what the user actually asked for, from the start of the session.
Meaningful groups: one short bold heading per workstream, its items beneath as a bullet list, each bullet led by a status marker (✅ / ⏳ / ❌ / 🛑 / ⚠️ / ◻️) and, when open, a (you) / (agent) owner tag. Fold the evidence (PR and issue links, file.js:line, commit hashes) and the why directly into the item it belongs to, not a separate list.
State check, one line at the end: whether the user is blocked and whether anything is needed from them, said outright. State "nothing needed from you" when that is true.

Example

A zero-context recap for a session that was adding Google OAuth login. The groups are workstreams, not "done" and "todo" buckets, and the failure, the blocker, and the caveat stay loud because each item carries its own marker.

🎯 Goal: add Google OAuth login so users can sign in without a password.

Auth flow

✅ Redirect + callback routes (auth/routes.js:40, commit a1b2c3d)
✅ Token exchange + session cookie
⏳ Token refresh on expiry (agent): implementing now
❌ Refresh test failing (auth/refresh.test.js): intermittent, fixing next
⚠️ Callback allows http on localhost only; must be https before prod launch

Account linking

🛑 Auto-link vs require confirmation (you): blocked on your decision
◻️ Link an OAuth identity to an existing email account (agent): not started

Rollout

◻️ Put the login button behind a feature flag (agent)

State check: blocked on one decision from you (auto-link vs confirm), and one test is failing. Nothing else needs you; I will fix refresh meanwhile.

Empty groups are omitted: with no rollout work yet, that group does not appear at all. The same session's always-on per-turn recap is far smaller, just the workstreams the turn touched:

Auth flow

✅ callback route landed
❌ refresh test flaky (agent, fixing next)
🛑 need your call on auto-link vs confirm before account linking

Principles

Verify before recapping, with cost as the dial. Checking real state beats trusting memory, and how hard you work at it scales with the cost of the check. Cheap verification (git status, gh, a quick look) is always done: never assert from memory something a five-second command would confirm. Expensive verification is a judgment call; if you skip it or cannot run it, say so and keep the item out of ✅. The rule of thumb: always verify when you can, and when you cannot, be explicit about it.
Honest per-item status carries the load. There is no dedicated "not wrapped up" section. Incompleteness is loud because every unfinished item wears an ⏳ / ❌ / 🛑 / ◻️ marker in its own group. Nothing is marked ✅ on the strength of memory, and anything you cannot confirm is flagged ⚠️ (say you could not verify it), never quietly promoted to done.
Self-contained. One message, no reliance on prior turns. The reader has zero context.
Chat-only. Print the recap to the conversation; do not write it to a file. Its value is keeping the human oriented in the moment, across many parallel agents. Persisting it is a non-goal.
Omit empty groups. Render a group only when it has something to say. An empty group is noise, not reassurance, so do not print placeholders like "None" or "nothing left." The one exception is the state check, which always appears.
Emoji-structured for at-a-glance scanning.

Recap Current Work ​

Two modes ​

The structural rule: group by meaning, mark status per item ​

What a zero-context recap contains ​

Example ​

Principles ​

See also ​