Writing the wrap-up for someone who wasn't watching

Before going to bed, I left Claude Code one line:

"I'm going to sleep. I want to see the site live tomorrow."

The job was building pdd.bot, the site you're reading now. Chinese and English, hosted on Cloudflare Pages. Copy, design, code, DNS, merging the PR: all of it was the agent's. The next day, the report it handed me opened like this:

Good morning, pdd.bot is live. Open https://pdd.bot to see it.

Needed from you: look over the 5 "decisions open to veto" below and tell me if you want any changed. Nothing else needs your hands.

Two lines, and both things I needed were there: it worked, and here's what I have to do.

It didn't write like that by default. There's a rule for it in my rules file.

If you've run an agent on a long task, you've seen the other kind of report. It checked the config, found a port conflict, switched to 8081; ran the tests, two failed, traced it to a time zone issue; then... all the way down to the last line, "Deployed to production."

Writing in the order things happened is natural for the writer. It just lived through it, so that's the easy way to tell it. But the reader wasn't there. They may have slept, or come out of three meetings with no context at all, and they have to read to the very end to learn whether it worked and whether they need to do anything.

The rule is one sentence

In my global CLAUDE.md (the rules file Claude Code reads at the start of every session), it says:

Write the wrap-up for someone who wasn't watching: explain IDs, acronyms, and internal names (migration numbers, doc code names) the first time they appear, give full URLs, and lead with the outcome and what the user needs to do, then the process.

The words doing the work are "someone who wasn't watching." They pin down the reader, and once the reader is fixed, the order flips on its own: did it work, what do I need to do, what do I need to decide, how was it checked, and the process last.

That report followed this order. After the outcome came "Done and verified": both home pages return 200, unknown paths return 404, http redirects to https, the certificate expires in February 2027 and Cloudflare renews it. Then 5 decisions open to veto, each with the choice and the alternative. The last section listed what wasn't done, including this line:

Not tested on a real phone. Only checked for horizontal scrolling in a 390-pixel-wide emulator.

I value that line. If the agent doesn't tell you it skipped the real device, you won't know, and by the time you find out, a user probably found out first.

The second half of the rule is easy to overlook: explain IDs, acronyms, and internal names the first time they appear.

The writer knows the names it just made up. The reader doesn't. The report said "a multi-agent pass implemented it, then reviewed it from four angles (visual fidelity, honest copy, accessibility and SEO, code conventions) and raised 19 issues," not just "went through the review workflow." The first tells me what happened; the second sends me back with questions. Same with links: give the full URL. "See the PR above" means nothing to someone who wasn't there.

The section that does the real work

That's the list of decisions open to veto.

During the copy round, the agent had listed one that put a line in the footer: "This is an independent project, not affiliated with any brand, company, or individual using the same name." When I saw it on the live site, I replied, "Let's not say any of this." It removed the line, opened a PR, merged it, and redeployed.

The work never waited on me, and I never lost the chance to say no. There's more to it than fits here, so it has its own essay: The veto list: the agent decides, a human can overrule.

Accurate beats polished

When I changed the footer the next day, my network couldn't reach Cloudflare and the deploy kept failing. The agent retried every 30 seconds in the background. The report said "The network came back and the 12th retry deployed successfully." Then it fetched the live page, confirmed the line was really gone, and only then called it done.

If it had said "should be deployed by now," I'd have checked everything myself, and the sentence would have saved me nothing. "Should be fine" may be the least useful line an agent can write in a report.

The rule has limits. For a short task you watched from start to finish, you don't need it. And it only governs how the report is written, not whether the checks happened. Whether the site really returns 200, whether the line is really gone, other rules have to make the agent verify, such as requiring every PR to state Validation, Risk, and Rollback. The report rule's job is to deliver what was verified, in the order the reader needs it.

A version to copy

Expanded, that one sentence becomes these five lines. Paste them into your project's CLAUDE.md (Codex reads AGENTS.md; the content is the same):

## Wrap-up reports
- Write for someone who wasn't watching: lead with the outcome and
  what you need from the reader, then the process
- If anything needs a human decision, list it under "Open to veto"
- Explain IDs, acronyms, and internal names the first time they
  appear; give full URLs
- Report honestly: paste output for failed tests, name skipped steps,
  say what wasn't verified
- If it's done and verified, say so plainly; no "should" or "probably"

Then test it on the agent's latest report: read only the first two lines. Can you tell whether it worked and whether you need to act? If not, revise the rule.

I went to bed asking to see the site live the next day. The first line of the next day's report said it was live. That's all I wanted.