Onboarding through review rules: nobody reads CONTRIBUTING.md, but everyone reads their PR feedback.

Every team has a CONTRIBUTING.md. Almost nobody reads it. The new hire glances at it on day one, picks up the basic git workflow, and never opens the file again. Three months later they’re making the same mistakes the document warns against, because nothing about the workflow surfaces those warnings when they matter.

The most effective onboarding document a team can have is the one that talks to the new hire on their first PR — not the one that talks to them on their first day. COMMITBRIEF.md happens to be that document, almost by accident. This post is about that property, what it implies for how you should write the file, and where the analogy breaks down.

The attention asymmetry

Documents have a relationship with attention. CONTRIBUTING.md gets attention once: when the new hire is told to read it. After that the attention drops to zero. The information in it has decayed in memory before it has a chance to be used.

PR feedback gets attention every single time a PR is reviewed. The new hire opens the comment, reads it, addresses it, and through that act actually internalizes whatever was being asked for. The feedback teaches by being delivered at the moment of relevance.

COMMITBRIEF.md lives in the second category, not the first. The rules you wrote in it are surfaced as findings on the new hire’s PRs. They don’t have to remember anything; the file remembers for them.

Three months in, the new hire has internalized the rules — not because they read them, but because they’ve addressed feedback derived from them dozens of times. That’s how procedural knowledge actually transfers.

A worked first-week scenario

A new backend engineer joins a Go team. The team has a COMMITBRIEF.md that, among other things, says:

- Forbidden: `database/sql`. Required: `pgx`. Don't bypass the
  repository pattern.
- Forbidden: log lines containing PII. Use `slog` with structured
  fields, pass sensitive fields through `.Mask()`.
- Every HTTP handler takes a `context.Context` and respects the
  parent timeout.

Day three, the new hire writes their first endpoint. It uses database/sql (their habit from the previous job), logs the user’s email in a debug line, and uses context.Background() because they hadn’t internalized the project’s context propagation patterns yet.

Their pre-PR self-review with commitbrief --staged flags all three. They don’t have to ask a teammate; they don’t have to remember reading something on day one; they don’t have to wait for a senior reviewer to leave the comments. They see the findings on their own machine, address them, and ship a PR that’s already aligned with the team’s norms.

By their tenth PR, those particular findings have stopped showing up because they’ve stopped writing the code that triggers them. The team has effectively onboarded them on three of its strongest norms without anyone spending a single moment of explicit mentoring time on those three norms.

What this means for how you write the file

If COMMITBRIEF.md is functioning as your onboarding document, the writing voice matters more than people usually assume. Two practical implications:

• Explain the why for non-obvious rules. “Forbidden: database/sql. Required: pgx.” A new hire who’s used database/sql for years will follow the rule but will resent it without context. “Required: pgx. We standardized on it for the prepared-statement caching; mixing with database/sql defeats the cache and creates session-pool fragmentation” — the rule plus the reason — does the onboarding work the rule alone can’t.
• Use concrete examples instead of abstract requirements. “Don’t write blocking I/O in HTTP handlers” is abstract. “If you find yourself reading a file or calling another service synchronously inside a handler, restructure it — see how internal/handlers/payments.go does the async pattern” is concrete. The second one teaches; the first one warns.

The anatomy post covered what not to write. The flip side of that, when you’re thinking about onboarding, is what to write more of: the context behind each rule, framed as if you were explaining it to someone you wanted to convince rather than someone you wanted to instruct.

When OUTPUT.md matters for new hires

The OUTPUT.md post talked about format as a personal preference. OUTPUT.md is a Go text/template applied locally to the parsed findings JSON, so it shapes the visible markdown but doesn’t change what the model decides to flag. For new hires specifically, I recommend a verbose preset that surfaces every field the schema carries — severity, file, line range, title, description, and the model’s suggestion — so each finding reads as a mini-lesson:

{{ range .Findings }}
### {{ upper .Severity }} — {{ .File }}:{{ .Line }}

**{{ .Title }}**

{{ .Description }}

> {{ .Suggestion }}
{{ end }}

A senior engineer might prefer a one-line-per-finding template because they’ve already internalized the team’s standards. A new hire is exactly the person who shouldn’t — they’re still building the model. A template that renders every field, instead of compressing them, makes the feedback function as a tutorial rather than as a checklist.

After a few months, the new hire can switch their personal ~/.commitbrief/OUTPUT.md to a terser shape. The fact that this is a per-user file, not a team one, is what makes the transition easy.

The model’s reasoning — the “why this finding, grounded in which rule” — lives in the system prompt and the model’s response. Tightening the rationale-quality of findings is COMMITBRIEF.md’s job: a rule that names the convention by name (“we standardized on pgx for prepared-statement caching”) gives the model the language to cite it in the description and suggestion fields.

Where the analogy breaks down

There’s a class of onboarding that COMMITBRIEF.md cannot do. Anything that requires judgment calls — when is a test worth writing, when is a refactor worth pursuing, when is “good enough” actually good enough — these don’t fit in rules. They live in conversation between a senior engineer and the new hire, in code review comments that explain context the rules don’t capture, in pair programming sessions, in 1:1s.

If a team treats COMMITBRIEF.md as the complete onboarding artifact and stops investing in human mentorship, the new hire will become technically aligned but culturally adrift. The rules teach them how to write code; humans teach them how to think about it.

I want to be careful with the framing. COMMITBRIEF.md is the best onboarding tool a team has for the things it can encode. It is not a substitute for the mentoring that addresses the things rules can’t encode. The two are complementary, and a team that runs both well will onboard faster than one running either alone.

The next post turns to a complementary dynamic: how commitbrief --staged between a junior and a senior changes the kind of mentorship that conversation produces.

← all posts