The structure, tone, and content rules that separate a client report that gets skimmed and archived from one that actually builds trust. Based on what we see inside commitplain-generated reports.
Most weekly client reports get skimmed for twenty seconds and then filed. The client opens the email on their phone between meetings, scans the subject line, glances at the first paragraph, and decides whether to read further. In over ninety percent of cases, they don’t. The report does its job as a receipt — proof that work happened — but it does nothing to build trust, surface risk, or give the client a reason to stay invested.
That’s a wasted channel. A weekly status report is one of the rare moments when the agency has the client’s full attention, in writing, with zero pushback on format. It should be the single most leveraged piece of communication in the engagement. Here is how to structure one that actually earns that attention.
The typical status report opens with a list of what the team did. Tickets moved, PRs merged, meetings attended. This is backwards. The client is not paying for activity; they are paying for outcomes. A good report opens with one or two sentences that describe what changed for the business this week.
“Checkout completion rose by 4% after the Stripe retry logic landed on Tuesday” is a lead. “Shipped 12 commits across 3 repos” is not a lead — it’s metadata. If the week genuinely had no business-visible outcome, say so plainly: “This week was internal plumbing; no customer-facing change.” The honesty itself builds more trust than an inflated summary.
Assume the client will give the report thirty seconds first, and a full read later only if the first thirty seconds suggested it was worth it. That means three reading tiers, ordered by information density:
The mistake most agencies make is to write only tier three, then hope the client reads it. The mistake is easy because tier three is the most natural output of the work: developers describe what they built, the project manager strings the descriptions together, done. The tiers one and two are extra effort — but they are the ones the client actually consumes.
Every week has at least one thing that slipped, blocked, or surprised the team. If the report omits all of these, it looks either dishonest or unobservant. If the report surfaces them calmly, with context, it does two things simultaneously: it protects the client from being blindsided later, and it signals that the agency is thinking ahead.
Format: one short paragraph at the end, labeled something like “Heads-up for next week.” Contents: the specific risk, why it matters, and what the team is doing about it. Not “we might miss the deadline,” but “the Segment migration is running 2 days behind the plan because the source data has more edge cases than the spec described; we’ve added a backfill job and expect to be caught up by Thursday.”
“Refactored the auth middleware” means nothing to a non-technical founder. “Rewrote the part of the system that checks who you are so we can add enterprise SSO without breaking existing logins” means everything. The goal is not to simplify what the team did; it’s to explain why the team did it. Every technical term that survives in the final report should carry weight — if the client would skip over it, cut it.
This is the single hardest part of the report to write well, and it is also the one that most directly determines whether the client renews the engagement. An agency that can translate its own work into the client’s language earns far more trust than one that demands the client learn to read commits.
The two worst things that can happen to a weekly report cadence are (a) the report skips a week, and (b) the report arrives at wildly different times on the chosen day. Both signal the same thing: the agency does not consider the report a first-class deliverable. Pick a day and a time, then honour it even when the week was quiet. “Not much shipped this week, here’s why” is a perfectly valid report; silence is not.
Most of what belongs in a weekly report is already in the commit history, the PR titles, and the branch names. The reason reports take 30-60 minutes to write is that teams re-derive that information from memory instead of reading the source of truth. The shortcut is obvious: start from the commits, not from the blank page. That is what commitplain does — it reads your real commit history, translates it into executive language in the tone you choose, and delivers a draft for your review before anything reaches the client. You review, edit if needed, approve, send. The report goes from a 45-minute Friday chore to a 3-minute review.
A good report is not a blank-page writing exercise. It is an editing exercise. Start from the facts — commits, PRs, outcomes — and cut until only the parts the client cares about remain.
commitplain reads your real GitHub commits and drafts an executive client report in your tone — reviewed and approved by you before anything reaches your client.
See how it worksJira tickets describe what you planned. Commits describe what you shipped. When those two diverge — and they always do — the client report should follow the commits.
6 min readNon-technical clients don't need to understand your code. They need to understand what changed for them, and why it was worth what they paid for it.
8 min readA reference checklist: what to keep, what to cut, and the exact order a client wants to see it. Seven sections, no filler.
7 min read