Reviewing work when you can't follow: the recap page
Coding agents now produce more code in a session than I can read line by line. They generate so much code, so fast, that I am almost under pressure to approve, and not be a bottleneck. Sometimes, I have to do a lot of experimentation, and while individual choices look easy to follow, by the end of the session, it leaves a lot of gaps in overall work.
So I end up looking at sessions through a different artifact, a recap page. It’s a disposable HTML page that lets me catch up on the session’s work from outside the code and the session messages. I thought of this approach after looking at how observability works, where I want to understand how the system is doing from outside using traces and metrics and logs.
This artifact has to answer exactly three questions, in order.
What are we doing
One plain sentence stating the goal, then the current state: what’s done and what’s in flight. This is derived from files changed, commits, tests passing, corpus sizes etc.
Why this way
A lot of decisions are accepted based on the recommendation of the AI. I frequently just say “works” when the work gets tiring. Another phrase that is becoming common is “looks good to me”. While this may work across individual decisions, the overall shape becomes very different from what was originally envisaged, and from there the lack of shared understanding arises. This step explains the choice, the rationale, and the alternative that was rejected, with why. If a decision is still open, it’s marked open. And this section is usually absent from git diff. Earlier, most companies tried unsuccessfully to solve this through code comments and Confluence docs. And this is what teams used to do while onboarding a new engineer. So I think of this step as AI agent onboarding me after every session.
How it works — with a hard rule
- A module map. Boxes are the components that matter, each labeled with its one responsibility. Arrows are who calls whom and what data flows. Main focus is on structure here.
- Traces. For each key flow, this workflow creates a sequence diagram which shows the path a request or a piece of data takes across modules and services, step by step. When I couldn’t draw the trace, it usually meant I didn’t understand the flow yet.
- A component-level change list. Each module touched and the role it now plays, without talking about diffs.
The hard rule: no source code on the page. Not even a snippet or a diff.
Accurate over pretty
The page is reconstructed from what actually happened and not from memory of the session. The agent re-reads the files it changed, walks the real git log, and draws the diagrams from that. A plausible-looking trace that doesn’t match the code is worse than no trace.
So now my judgment goes to the approach, the decisions, and the shape at an abstraction where I can hold the whole concept in my head. Line-by-line correctness is checked by tests, linters, and targeted reading of the places the recap page marks as unclear.