Standup: “No blockers.” The pull request timeline: opened Tuesday, first review request routed to a team, no human response until Friday. Both statements are true. That is the problem.

This is a postmortem for a class of incident that never gets declared: the review queue that everyone reports as empty because nobody is measuring it. The artifact trail is already there. You just have to read it.

Symptom

Engineers report no blockers. Delivery dates slip anyway. The gap between “work complete” and “merged” grows, but it does not appear in any status report because status reports are self-assessed and the queue is invisible to the person standing in it.

The failure mode is not lying. It is a measurement boundary problem. Standup asks a person a question about their own state. The bottleneck lives at a system boundary between people, where no individual owns the wait.

Timeline

Reconstruct it from artifacts, not memory.

1. PR opened. GitHub automatically requests review from code owners when a pull request modifies code they own, per GitHub’s CODEOWNERS documentation. The request is generated. Whether a human sees it is a separate question.
2. Review requested, no response. The review sits in REQUESTED state. The PR author’s local work is done. From the author’s seat, there is no blocker — they are waiting on someone else, which they classify as normal latency, not a blocker.
3. Author pings in Slack. Not logged as an artifact unless you keep the channel. The ping is the real signal that the queue is stuck, and it is the one signal most teams do not retain.
4. Review submitted. The Pull Request Reviews API returns reviews in chronological order with a state and a submitted_at timestamp. That timestamp is the end of the wait. The start is the review request event, which lives in the PR timeline, not the reviews endpoint.
5. Changes requested. State flips to CHANGES_REQUESTED. The clock resets. A second wait begins.
6. Approved and merged. Total elapsed time from open to merge is the number that never made it into standup.

Contributing factors

1. The question is wrong

“Any blockers?” asks about the individual’s ability to proceed. A reviewer who has not looked at the PR is not blocking the author’s ability to work — the author has already finished. The wait is real; the framing hides it.

2. CODEOWNERS routes requests, not attention

GitHub’s documentation is explicit: code owners are automatically requested for review when a PR modifies code they own, and code owners are not automatically requested for draft pull requests. When a draft is marked ready, code owners are notified. That is routing. It says nothing about whether the owner has capacity, is on call, or is on leave.

Two details matter for diagnosis. First, if a CODEOWNERS line contains invalid syntax, that line is skipped — meaning a typo can silently remove an owner from the routing table. Second, if you specify a user or team that does not exist or has insufficient access, no code owner is assigned. A PR can therefore be “waiting on review” with no reviewer ever requested. That is not a slow reviewer. That is a broken routing rule.

3. Required reviews create a deadlock surface

Repository administrators can require approvals before merge, and can require review from code owners. When reviews from code owners are required, an approval from any one of the listed owners is sufficient — approvals from all are not required. That is a relief valve. But if the only listed owner is a single person or a team with one active member, the approval gate becomes a single point of failure. The PR is not blocked by a person’s judgment. It is blocked by an org chart.

4. CI retries mask a second queue

Workflow run logs record whether a run succeeded, failed, canceled, or was neutral, and they record the time each step took. They also record “Set up job” and “Complete job” steps that GitHub adds to every job. If your PRs routinely show three or four re-runs before green, the review wait is not the only hidden queue. The CI queue is the other one, and it is visible in the logs if anyone looks.

One caveat from the same documentation: when you download the log archive for a workflow that was partially re-run, the archive only includes the jobs that were re-run. To get a complete picture, you must download the log archives for the previous run attempts. Teams that pull one archive and call it the history will undercount retries.

5. The standup is a self-report, and self-reports are lossy

DORA’s capability research treats visibility of work in the value stream and work-in-process limits as capabilities that drive delivery performance. A standup that asks each person for a verbal status is not a value-stream view. It is a set of independent self-assessments. The queue between people does not appear in any of them.

What the artifacts actually show

Pull the data before you pull the person aside.

Artifact	Signal	What it can and cannot tell you
CODEOWNERS file	Routing rules, invalid lines, single-owner paths	Shows who should be requested. Does not show capacity or availability.
PR timeline	Review request event, draft-to-ready transition	Shows when the clock started. Does not show whether the reviewer saw the notification.
Pull Request Reviews API	state and submitted_at per review, chronological	Shows when the wait ended. Does not show the start of the wait by itself.
Workflow run logs	Success/failure/canceled/neutral, per-step timing, re-run history	Shows CI retries and queue time. Partial re-runs require multiple archives.
On-call swap logs	Reviewer availability during the wait window	Explains why a request went unanswered. Does not excuse a missing backup owner.

The reviews endpoint gives you the end timestamp. The PR timeline gives you the start. Subtract. That number is your review latency, and it is the number that never appears in standup.

Action items

Action item 1: Measure review latency from artifacts, not memory

For a sample of merged PRs, compute time from review request to first review submission. Use the PR timeline for the request event and the reviews endpoint for the submission. Do not ask engineers to estimate. Estimates of waiting are systematically low because waiting is not memorable work.

Action item 2: Audit CODEOWNERS for single points of failure

List every path with exactly one owner or one team. For each, ask: what happens when that owner is on leave, on call, or in a different time zone? If the answer is “the PR waits,” you have found a structural bottleneck. Add a second owner or a fallback team. This is a reversible change with a clear rollback: revert the CODEOWNERS commit.

Action item 3: Check for silently skipped lines

GitHub highlights errors when you navigate to the CODEOWNERS file, and a list of errors is accessible via the API. Run that check. A skipped line is a routing failure that looks like a slow reviewer.

Action item 4: Separate CI queue time from review queue time

Pull workflow run logs for the same sample. Record time from PR open to first workflow start, and count re-runs per PR. If CI queue time is a meaningful fraction of total lead time, the review conversation is a distraction. Fix the queue you actually have.

Action item 5: Change the standup question

Stop asking “any blockers?” Ask “what are you waiting on, and who owns it?” The second question surfaces cross-boundary waits. It also produces a name, which is the only thing that makes a wait actionable.

What this method cannot tell you

Artifact-based diagnosis has confounders. A long review latency might mean a slow reviewer, a missing reviewer, a PR that was too large to review quickly, a holiday, an incident that consumed the reviewer’s week, or a CODEOWNERS rule that routed to the wrong team. The artifacts narrow the hypothesis space. They do not close it.

Git history and PR metadata also reflect process, not intent. A team with a healthy review culture and a team with a broken one can produce similar timestamps for different reasons. Treat the numbers as a starting point for a conversation, not a verdict about a person.

The one thing the artifacts do reliably is contradict the standup. When the log says “waiting on review” and the standup says “no blockers,” the log is the more useful document.

FAQ

Can the Pull Request Reviews API tell me how long a PR waited for review?

Not by itself. The reviews endpoint returns reviews in chronological order with a state and a submitted_at timestamp. That gives you the end of the wait. You need the review request event from the PR timeline to get the start. Combine the two.

Why did no reviewer get requested on my PR?

Check three things. First, the CODEOWNERS file must be on the base branch of the pull request for code owners to receive review requests. Second, if a line contains invalid syntax, that line is skipped. Third, if you specify a user or team that does not exist or has insufficient access, no code owner is assigned. Any of these produces a PR that looks like it is waiting on a reviewer who was never asked.

Does requiring code owner review mean every owner must approve?

No. GitHub’s documentation states that when reviews from code owners are required, an approval from any one of the owners is sufficient. Approvals from all listed owners are not required. The risk is not multiple approvals; it is a single listed owner with no backup.

How do I get complete CI retry history?

Download the log archives for every run attempt, not just the latest. When a workflow is partially re-run, the archive for that run only includes the jobs that were re-run. The earlier attempts hold the rest.

Is review latency a DORA metric?

DORA’s published capability set includes lead time for changes and visibility of work in the value stream, among other capabilities. Review latency is a component you can measure from repository artifacts; it is not a standalone DORA metric. Use it as a local diagnostic, not a benchmark against published research.

Symptom: The incident count for last quarter looks flat. The review calendar says you held every postmortem. The git history says otherwise.

Timeline: A team changes its postmortem review cadence from weekly to monthly. Six weeks later, a Sev-2 that would have been reviewed in the old cadence is closed with a Slack thread and a rollback. No postmortem document is created. The incident does not appear in the quarterly reliability report. The review calendar still shows a meeting occurred.

Contributing factors: The calendar is treated as the record. The artifacts that actually preserve incident history — postmortem documents, incident channels, commit messages, CODEOWNERS changes, CI retry logs — are not cross-checked against it. When the cadence changes, the calendar overwrites the history it was supposed to preserve.

This is a predictable failure mode of any review process that relies on a scheduled meeting as its primary evidence. The meeting is a container. The artifact is the record. When the container changes shape, the record leaks.

What the review calendar actually controls

A review calendar does three things, and only one of them is visible on the calendar.

First, it sets the trigger threshold for what gets reviewed. Google’s SRE book describes common postmortem triggers: user-visible downtime beyond a threshold, data loss, on-call intervention, resolution time above a threshold, and monitoring failure. The book is explicit that these criteria should be defined before an incident occurs so everyone knows when a postmortem is necessary. A calendar change that moves review from weekly to monthly does not change the trigger criteria on paper. It changes the practical threshold, because incidents that resolve before the next review slot are more likely to be closed informally.

Second, it sets the review latency. Atlassian’s incident management guidance recommends drafting the postmortem immediately after a post-incident review held within 24–48 hours of resolution, and not more than five business days. The Google SRE Workbook’s case study of a bad postmortem notes that a four-month publication delay meant team members likely forgot key details, and the incident recurred in the interim. Latency is not neutral. It is a lossy compression algorithm applied to operational memory.

Third, it sets who is in the room. The Google SRE book describes a formal review step where senior engineers assess the draft for completeness: whether key incident data was collected, whether impact assessments are complete, whether the root cause is sufficiently deep, whether the action plan is appropriate, and whether the outcome was shared with relevant stakeholders. Change the cadence and you change the reviewer pool. Change the reviewer pool and you change what counts as a complete postmortem.

How the calendar rewrites history

The rewrite is not malicious. It is a side effect of using the calendar as the index and the postmortem as the content. When the index changes, the content that no longer fits the index becomes invisible.

Consider a concrete sequence. A team holds weekly incident review meetings. Every incident above a severity threshold gets a postmortem document, a review slot, and a line in the weekly notes. The calendar is dense. The artifacts are dense. The two match.

Now the team moves to monthly review. The meeting still happens. The postmortem template is still available. But the weekly slot is gone. An incident that resolves on a Tuesday and would have been reviewed on Thursday now waits three weeks. By the time the monthly meeting arrives, the incident channel has been archived, the on-call engineer has rotated, and the rollback commit is buried under three weeks of merges. The postmortem is either written from memory or skipped. The calendar shows a meeting. The artifact record shows a gap.

This is the mechanism. The calendar does not delete the incident. It deletes the review of the incident, and the review is what produces the durable artifact. Without the artifact, the incident is not part of the organizational record. It is a Slack thread that will be lost when the workspace retention policy kicks in.

Artifacts that preserve incident history

If the calendar is unreliable as a record, what is reliable? The artifacts teams already generate. Here is what to pull and what each one tells you.

Postmortem documents

The postmortem is the primary record. Google’s SRE book defines it as a written record of an incident, its impact, the actions taken to mitigate or resolve it, the root cause(s), and the follow-up actions to prevent recurrence. The book also states that an unreviewed postmortem might as well never have existed. That is the standard to hold the calendar to: if the calendar shows a review but no postmortem document exists, the review did not happen in any way that matters.

Pull the postmortem repository and sort by incident date, not publication date. The gap between the two is a latency metric. A postmortem published four months after the incident is not a record of the incident. It is a record of what someone remembered four months later.

Incident channels

The incident channel is the raw log. It contains the timestamps, the hypotheses, the dead ends, and the moment someone said “wait, this looks like the thing from March.” That last one is the signal. If the same failure mode appears in two incident channels and only one has a postmortem, the review calendar has a hole in it.

Search incident channels for the phrase “this is the same as” or “didn’t we fix this.” Each hit is a candidate for a missing postmortem. Each missing postmortem is a candidate for a calendar that is not capturing what it claims to capture.

Git history

Git log is the timeline of what actually changed. The git log documentation describes it as showing commit logs in reverse chronological order by default, with options to limit by date, author, and message pattern. That is enough to reconstruct a change timeline independent of any postmortem.

Pull the commits around the incident window. Look for the rollback commit, the hotfix, the revert. Then check whether a postmortem exists for that window. If a revert commit exists and no postmortem exists, the incident happened and the review process missed it.

The commit message is also evidence. A message that says “revert #1234, fixes prod” is an incident marker. A message that says “revert #1234, see postmortem PM-456” is a linked record. The difference between the two is the difference between an incident that is traceable and one that is not.

CODEOWNERS changes

CODEOWNERS files define who is responsible for code in a repository. GitHub’s documentation states that code owners are automatically requested for review when someone opens a pull request that modifies code they own, and that branch protection can require approval from a code owner before merge. The file is a map of ownership at a point in time.

When a CODEOWNERS file changes, the ownership map changes. If a service’s code owner changes in the same week as an incident, the incident review may have been conducted by someone who no longer owns the code. The postmortem may name an owner who has since been removed. The action items may be assigned to a team that no longer exists.

Pull the CODEOWNERS history and align it with the incident timeline. A CODEOWNERS change during an incident window is a contributing factor to review confusion. It is not the cause of the incident, but it is a cause of the incident being misattributed.

CI retry logs

CI retry logs are the least glamorous artifact and the most honest. A retry is a signal that something failed and someone decided to try again rather than investigate. A cluster of retries around a deploy window is a signal that the deploy was flaky and the team normalized the flakiness.

This is normalization of deviance in its purest form. The alert that fires every Tuesday and gets acknowledged without action is the same pattern. The CI job that fails twice and passes on the third try is the same pattern. Neither generates a postmortem because neither crosses the severity threshold. Both are evidence that the threshold is wrong.

Pull the retry logs for the quarter. Count retries per pipeline. A pipeline with a rising retry rate is a pipeline with a rising incident rate that the review calendar is not capturing.

On-call swap logs

On-call swap logs are the artifact that connects incident history to human history. A swap is a signal. It can mean a vacation, a conflict, or a refusal to carry the pager for a service that pages too often. The last one is the signal that matters.

Pull the swap logs and align them with the incident timeline. A spike in swaps after a series of incidents is a retention risk. A spike in swaps before a known incident is a leading indicator. Neither appears in the postmortem. Both appear in the swap log.

PIP timelines and exit interview notes

This is where the review calendar does the most damage. A performance improvement plan that starts two weeks after an incident is a data point. An exit interview that mentions on-call burnout is a data point. Neither is a postmortem. Both are evidence that the incident review process failed to surface a system problem and the problem was attributed to a person instead.

The Google SRE book is explicit on this point: blameless postmortems focus on identifying contributing causes without indicting any individual or team, because a culture of finger pointing leads people to withhold information. The book states that you cannot fix people, but you can fix systems and processes. When a PIP timeline aligns with an incident timeline, the question is not whether the person failed. The question is whether the system failed to give the person what they needed.

Pull the PIP start dates and the incident dates. Align them. A PIP that starts within 30 days of an incident that has no postmortem is a misattribution waiting to be documented.

How to run the forensic pass

This is a procedure, not a philosophy. It takes one afternoon and produces a list of gaps.

Step 1: Pull the calendar. Export the review meeting invites for the last two quarters. Note the cadence, the attendees, and the dates.

Step 2: Pull the postmortems. Export the postmortem documents for the same period. Sort by incident date. Note the publication date for each.

Step 3: Align the two. For each review meeting, list the postmortems discussed. For each postmortem, list the review meeting where it was discussed. The gaps are the incidents that have a review slot but no postmortem, and the postmortems that have no review slot.

Step 4: Pull the git log for the same period. Use git log --since and git log --until to bound the window. Search for revert commits, hotfix commits, and commit messages that mention production. Each one is a candidate incident.

Step 5: Cross-check. For each candidate incident from git, check whether a postmortem exists. For each postmortem, check whether a revert commit exists. The mismatches are the rewrites.

Step 6: Pull the CODEOWNERS history. Use git log --follow CODEOWNERS to see the ownership changes. Align them with the incident timeline. Note any incident where the code owner changed during the incident window.

Step 7: Pull the CI retry logs. Count retries per pipeline per week. Plot the trend. A rising trend is a leading indicator of incidents that the review calendar is not capturing.

Step 8: Pull the on-call swap logs. Count swaps per week. Align with the incident timeline. A spike in swaps is a signal that the on-call load is not sustainable, regardless of what the postmortem says.

Step 9: Pull the PIP timelines and exit interview notes. Align the start dates with the incident dates. Note any PIP that starts within 30 days of an incident with no postmortem.

Step 10: Write the gap report. The report is not a postmortem. It is a list of incidents that the review calendar missed, with the artifact that proves each one. The report goes to the same people who own the review calendar.

One reversible experiment

The experiment is this: add a second review slot, not a replacement. Keep the existing cadence. Add a 15-minute weekly slot whose only agenda item is “what happened this week that we did not review.” The slot has no postmortem requirement. It has one output: a list of incidents that did not cross the threshold.

The rollback plan is simple. If the slot produces no items for four consecutive weeks, cancel it. If it produces items, the items are the evidence that the threshold is wrong. The threshold can then be adjusted with data rather than opinion.

This experiment is reversible because it adds a meeting, not a process. It does not change the postmortem template. It does not change the severity definitions. It does not change the review calendar. It adds a sensor. The sensor either reads something or it does not. Either outcome is information.

The experiment also has a second output: the list of incidents that did not cross the threshold is a list of candidates for the forensic pass described above. The weekly slot is the intake. The forensic pass is the analysis. The two together are the mechanism for detecting when the review calendar is rewriting the incident history.

What to do with the gap report

The gap report is not a blame document. It is a map of where the review process is not matching the operational reality. The map has three uses.

First, it corrects the record. The incidents that were missed are added to the incident repository with a note that they were identified retroactively. The note is important because it distinguishes a postmortem written at the time from a postmortem written after the fact. The Google SRE Workbook’s case study of a bad postmortem is explicit that delayed publication loses detail. A retroactive postmortem is better than no postmortem, but it is not the same artifact.

Second, it corrects the threshold. The incidents that were missed are the data points that define the new threshold. If the weekly slot produces five incidents in a month that did not cross the old threshold, the old threshold was wrong. The new threshold is defined by the data, not by the calendar.

Third, it corrects the attribution. The PIP timelines and exit interview notes that align with missed incidents are the evidence that the system failure was misread as a personal failure. The gap report does not reverse a PIP. It does provide the context that the PIP process did not have.

Why this matters

The review calendar is a coordination mechanism. It tells people when to show up and what to bring. It is not a record. When it is treated as a record, it overwrites the artifacts that are. The overwrite is silent because the calendar still shows a meeting. The meeting still happened. The postmortem did not.

The fix is not to abolish the calendar. The fix is to stop using it as the index. The index is the artifact. The calendar is the schedule. When the two disagree, the artifact wins. That is the rule. Everything else is a process detail.

The rule has a corollary: if the artifact does not exist, the incident did not happen in any way that the organization can learn from. The calendar cannot fix that. Only the artifact can.

FAQ

Does this mean every incident needs a postmortem?

No. Google’s SRE book is explicit that the postmortem process has an inherent cost and that teams are deliberate in choosing when to write one. The point is not to postmortem everything. The point is to know which incidents were not postmortemed and why. The gap report is the record of that decision. Without it, the decision is invisible and the calendar becomes the only record.

What if the review calendar is working?

Then the forensic pass will show that the postmortems and the calendar align. That is a useful result. It means the review process is capturing what it claims to capture. The pass is not an accusation. It is a verification. Verification that passes is still verification.

How do I get the artifacts if the team does not keep them?

Start with git. The git log is the most durable artifact because it is version-controlled by default. The git log documentation describes options for limiting by date, author, and message pattern. That is enough to reconstruct a change timeline even if no postmortem exists. The incident channel is the next most durable, depending on the retention policy. The postmortem repository is the least durable if it is not maintained, because a postmortem that is not reviewed is, in the words of the Google SRE book, a postmortem that might as well never have existed.

What if the CODEOWNERS file does not exist?

Then the ownership map is implicit. GitHub’s documentation states that CODEOWNERS files must be placed in .github/, the root, or docs/, and that GitHub searches those locations in that order and uses the first one it finds. If no file exists, ownership is defined by commit history and team conventions. That is a weaker artifact, but it is still an artifact. The commit history shows who touched what. The team conventions show who was expected to. The gap between the two is the ownership ambiguity that contributes to incident misattribution.

How often should the forensic pass run?

The pass is cheap. It is a query against artifacts that already exist. Run it quarterly, aligned with the review calendar’s own reporting cycle. The output is a gap report that either confirms the calendar or corrects it. Either outcome is better than assuming the calendar is the record.

Incident: A senior engineer’s promotion packet claims “led the migration that cut p99 latency by 40%” and “drove adoption of the new service mesh across three teams.” The packet is well-written. The committee is split. Nobody can find the migration RFC, the latency dashboard, or the adoption tracker. The packet is the only artifact.

Status: Open. Severity: Medium. Impact: The committee is now evaluating writing quality, not engineering impact. The engineer may be promoted or denied for reasons unrelated to their work. Both outcomes are wrong.

Symptom

The packet reads like a postmortem with the timeline removed. Claims are stated as facts. Numbers appear without units or baselines. Verbs are transitive but the objects are vague: “drove,” “led,” “owned,” “partnered with.” There is no artifact trail — no RFC link, no PR series, no dashboard snapshot, no incident review, no design doc with the engineer’s name in the revision history.

This is not a lying problem. It is a missing-artifact problem. The engineer did work. The work left traces. The traces are not in the packet. The committee is asked to reconstruct impact from prose.

Timeline

Promotion packets are usually assembled under deadline. The manager asks for a draft. The engineer writes it from memory, often late at night, often after a sprint. The manager edits for tone. The committee reads it cold, without the engineer in the room. The packet becomes the primary source.

If the packet cites artifacts, the committee can verify. If it does not, the committee either trusts the prose or discounts it. Neither is a system for evaluating engineering work. It is a system for evaluating packet-writing.

Contributing factors

1. The artifact trail is not part of the promotion process

Most engineering organizations have a career ladder and a promotion committee. Few have a requirement that impact claims link to artifacts. The ladder describes levels. The packet describes the engineer. The artifacts sit in git, CI, dashboards, and chat, unlinked.

This is a process gap, not a personal failing. The engineer is asked to prove impact in a format that does not require proof.

2. Impact is measured in outcomes, but artifacts record activity

Git history records commits. CI logs record builds. Incident channels record pages. None of these directly record “cut p99 latency by 40%.” That number lives in a dashboard, a query, or a before/after measurement. If the measurement was never saved, the claim is unverifiable.

This is the core mismatch: promotion packets claim outcomes, but the operational evidence teams generate records activity. The bridge between them — a saved measurement, a linked dashboard, a written before/after — is usually missing.

3. The committee has no shared standard for evidence

One committee member wants a design doc. Another wants a dashboard. Another wants peer feedback. Without a defined evidence standard, the committee defaults to prose quality and familiarity. This is how promotion becomes a writing contest with a social graph.

4. Retry storm: the same claims get re-litigated

When a packet lacks artifacts, the committee revisits the same claims in every calibration session. The claims do not resolve because there is nothing to resolve them against. This is a retry storm: the same request, the same failure, repeated until someone gives up or the deadline passes.

5. Normalization of deviance: everyone knows packets are unverifiable

The organization has learned that packets are mostly prose. The committee has learned to read between the lines. The manager has learned to write confidently. The engineer has learned to claim broadly. This is normalization of deviance: a known-bad practice that persists because it has not yet caused a visible failure. The visible failure is a bad promotion decision. It happens. It is attributed to the individual, not the process.

What the artifacts actually show

Pull the artifacts the team already generates. They tell a different story than the packet.

• CODEOWNERS: Who is actually required to review changes in the affected area? If the engineer is not an owner, “led the migration” needs a different artifact.
• Git history: Commit volume is not impact. But a series of commits across a migration window, with review approvals from other teams, is a trace. So is the absence of commits during the claimed period.
• CI retry logs: If the migration introduced flaky tests that were retried for weeks, the packet’s “cut latency” claim may be true while the operational cost is omitted.
• RFC threads: Who wrote the RFC? Who approved it? Who raised the blocking concern? The thread records the decision and the dissent.
• Incident channels: Did the migration cause an incident? Was the engineer on call? Did they write the postmortem? The channel records the response, not the narrative.
• On-call swap logs: If the engineer swapped out of on-call during the migration, that is a fact. It may be justified. It is still a fact.
• Exit interview notes: If the migration drove someone out, the notes may say so. This is uncomfortable and relevant.
• Career ladder docs: What does the ladder actually require at the next level? If it requires “impact across teams,” the packet needs cross-team artifacts, not a list of meetings.
• PIP timelines: If a teammate was on a PIP during the migration, the packet’s “led the team” claim needs context.
• Onboarding docs: If the migration required new onboarding steps, the doc is an artifact. If it did not, the migration may not have changed the system’s surface area.

None of these artifacts prove impact by themselves. Together, they form a trail. The trail either supports the packet’s claims, contradicts them, or is silent. Silence is a finding.

Why this gets misread as a personal failing

When the committee cannot verify a claim, it does one of two things. It trusts the engineer, or it discounts the engineer. Both are personal judgments. Neither is a system judgment.

The engineer who writes well and has a good reputation gets trusted. The engineer who writes plainly and has less visibility gets discounted. The difference is not impact. The difference is artifact trail and narrative skill.

This is the system failure: the promotion process rewards packet-writing and reputation, then attributes the outcome to engineering ability. The engineer who is denied is told to “build more visibility.” The engineer who is promoted is told they “demonstrated impact.” Neither feedback addresses the missing artifact trail.

Action items

For the committee: require artifact links for every impact claim

A claim without an artifact is a hypothesis. The committee can still consider it, but it should be labeled as unverified. This is not a punishment. It is a calibration. The committee’s job is to evaluate evidence, not prose.

Define the acceptable artifact types. A dashboard link with a saved query is an artifact. A PR series with review approvals is an artifact. A design doc with revision history is an artifact. A Slack thread is weaker but still an artifact. A verbal claim is not.

For managers: build the artifact trail before the packet deadline

The packet is a summary, not a discovery process. If the manager is writing the packet from scratch at deadline, the artifacts are already lost. Keep a running document per engineer: links to RFCs, dashboards, incident reviews, and peer feedback. This is not surveillance. It is the same evidence the committee needs.

For engineers: save the measurement, not just the outcome

When you run an experiment, save the before and after. When you ship a migration, link the dashboard. When you write an RFC, keep the thread. When you respond to an incident, write the postmortem. These are the artifacts that make impact legible.

This is not self-promotion. It is record-keeping. The organization already generates the evidence. The engineer’s job is to not lose it.

For the organization: define the evidence standard once

Publish the artifact types the committee accepts. Publish the format for linking them. Publish the rule that unverified claims are labeled. This removes the ambiguity that turns promotion into a writing contest.

HM Treasury’s Magenta Book provides a useful external reference for evaluation design: it emphasizes that evaluation should be built into an intervention’s design and delivery from the earliest stages, and that results need to be interpreted and presented with care. The same principle applies here. If impact evaluation is bolted on at packet time, the evidence is weak. If it is built into the work, the evidence is already there.

One reversible experiment

Pick one upcoming promotion packet. Before the committee reads it, ask the engineer and manager to add artifact links to every impact claim. If a claim has no artifact, mark it “unverified.” Run the committee session as usual. Compare the discussion to the previous cycle.

Rollback plan: If the artifact requirement slows the process without improving decisions, revert to the previous format for the next cycle. The experiment is reversible because it changes the packet format, not the promotion criteria.

What to measure: Did the committee spend less time debating unverifiable claims? Did the packet’s claims survive contact with the artifacts? Did any claim get withdrawn or narrowed? These are signals, not proof. But they are more useful than another cycle of prose review.

FAQ

Doesn’t requiring artifacts disadvantage engineers who work on invisible infrastructure?

It disadvantages engineers whose work leaves no artifacts. Infrastructure work leaves artifacts: dashboards, runbooks, incident reviews, migration RFCs, on-call logs. The problem is not invisibility. The problem is that the artifacts are not linked to the packet. If the work truly leaves no trace, that is a finding about the work, not the engineer.

Isn’t this just bureaucracy?

It is record-keeping. The organization already generates the artifacts. The packet currently ignores them. Linking them is less work than re-litigating the same claims in every calibration session.

What if the engineer did the work but the artifacts are owned by someone else?

Then the packet should say so and link the artifact. Ownership of the artifact is not the same as contribution to the outcome. The committee can evaluate contribution from the artifact trail: review approvals, RFC comments, incident response, commit history. The artifact does not need to be authored by the engineer. It needs to be linked.

How does this relate to the career ladder?

The ladder defines the expected level of impact. The artifacts define whether the impact occurred. If the ladder says “impact across teams,” the packet needs cross-team artifacts. If the ladder says “technical leadership,” the packet needs design docs, RFCs, or incident reviews. The ladder is the standard. The artifacts are the evidence.

What about qualitative impact, like mentoring or culture?

Qualitative impact still leaves artifacts: onboarding docs, peer feedback, exit interview notes, promotion packets of people the engineer mentored. These are weaker than dashboards but stronger than prose. The committee can weigh them accordingly.

Closing note

The packet is not the problem. The missing artifact trail is the problem. The packet is a symptom. The system failure is that promotion decisions are made on prose when the organization already generates evidence. Fix the trail, and the packet becomes a summary instead of a mystery.

The Architecture Decision Record That Records the Decision But Not the Duress

The ADR is supposed to be institutional memory. What actually gets merged is the clean version. Six months later, a new engineer reads a confident decision and reverse-engineers a rationale that never existed.

SYMPTOM // REVERSE-ENGINEERED RATIONALE

A team I’ll call the Marlow group had a service that handled payment webhooks. Single-tenant Postgres instance, no read replicas, no connection pooling, and a max connections setting that the original engineer had guessed at. When the service started timing out under load, the team wrote an ADR proposing a migration to a connection pooler in front of a multi-tenant cluster. The ADR was clean. Context section, decision section, consequences section. Alternatives listed. Approved. Also fiction.

The migration had been proposed because the original engineer — the one who guessed at the max connections setting — had left three months earlier, and the person who inherited the service didn’t know how to tune Postgres. The ADR framed this as a scaling decision. The actual context was a knowledge gap and a deadline. The dissenting voice in the RFC thread — a backend engineer who had argued for trying pgbouncer on the existing instance first — was overruled in a meeting that wasn’t referenced in the document. Their comments were in the thread. But the reply that closed the discussion — “Let’s go with the migration, we can revisit pooling later” — was timestamped 11 PM on a Friday. The engineer who objected went on vacation the next morning. By the time they came back, the ADR was merged.

Six months later, a new hire read the ADR and concluded that the team had deliberately chosen a multi-tenant architecture for long-term scalability. They built new services on the same pattern. When one of those services hit the same connection exhaustion problem, they assumed it was a different bug — because the ADR said the pattern was chosen for scaling, not because of a knowledge gap. The rationale they inherited was a story the team told after the fact. It was not the reasoning that produced the decision.

I’ve watched this pattern break at least four teams. Not the Postgres part — the documentation part. The ADR, the RFC thread, the technical strategy document: these are supposed to be the institutional memory of why we chose what we chose. But the artifact that gets merged or approved is almost always the clean version. The dissenting comments, the “I disagree but won’t block” caveats, the concerns raised in a side channel that never made it into the thread — that’s the actual decision context. And it’s the part nobody writes down.

§ 1 — WHAT THE ARTIFACT HIDES

The function of an ADR is to preserve decision context across time and team turnover. The failure mode is that the artifact preserves the outcome but strips the duress. Duress is the pressure under which the decision was actually made: the deadline, the missing expertise, the political constraint, the person who disagreed but was too tired to fight. Strip the duress and you leave behind a decision that looks rational and deliberate. The next reader assumes it was.

Google’s SRE book dedicates an entire chapter to postmortem culture and the principle that documenting what actually happened — including the messy, uncomfortable, politically charged reality — is the only way an organization learns from failure rather than repeating it with better confidence. The Google SRE book’s postmortem culture chapter is the closest established parallel to this problem: the gap between the clean summary and the actual timeline is where institutional knowledge dies. The same principle applies to ADRs. A postmortem that records the outage but not the contributing factors teaches nothing. An ADR that records the decision but not the duress teaches the wrong thing.

The specific signals of suppressed dissent are in the artifact itself. You just have to know what to look for.

§ 2 — THE FORENSIC READ

Pull the last five merged ADRs or approved RFCs from your team’s repository. For each one, inspect these four signals:

1. Comment threading depth versus final document depth. Count the nested reply levels in the discussion thread. Then check whether the concerns raised in the deepest branches appear in the final document. If the thread has four levels of nested replies and the ADR’s Alternatives Considered section has two sentences, you have a gap. The deepest branches are where the real disagreement lives — that’s where someone stops arguing with the proposal and starts arguing with the person who made it. If that content doesn’t surface in the ADR, the document is hiding the decision’s actual shape.

In the Marlow group’s ADR, the thread had a branch that went five levels deep on whether pgbouncer in transaction mode would break prepared statements. The final ADR’s alternatives section said: “Connection pooling was considered but deemed insufficient for projected scale.” No mention of prepared statements. No mention that the objection was technical, not strategic. The sentence reads as if pooling was evaluated and dismissed on its merits. The thread shows it was dismissed because the person who understood the tradeoff went on vacation.

2. Edit timestamps versus comment timestamps. Most RFC tools and wiki platforms expose edit history. Compare the document’s last edit time to the last substantive comment. If the document was edited after the last comment without that comment’s content being incorporated, you’re looking at a decision that was finalized by editing, not by discussion. The edit is where the author quietly resolved the disagreement by removing it from the record.

This is the most common suppression pattern I see. Someone raises a concern. The author agrees to “address it” in the document. The edit that follows doesn’t address it — it reframes it. The concern about prepared statements becomes “transaction mode limitations.” The concern about timeline pressure becomes “phased rollout recommended.” The original objection is gone. In its place is a passive-voice recommendation that nobody is accountable for.

3. The gap between Approved and the last substantive objection. Measure the time between the final substantive technical objection and the approval. If it’s under 24 hours, and especially if it’s under 4 hours, the approval happened before the objection could be resolved. This doesn’t mean the decision was wrong — it means the process didn’t include the objection. The objection existed, was recorded, and was overridden by time pressure, not by argument.

In a healthy process, the gap between the last objection and the approval reflects the time it took to address the objection. In a broken process, the gap reflects the time it took for the objector to give up. You can’t tell the difference from the document alone — but if the document doesn’t mention the objection at all, you can infer which one happened.

4. The conspicuous absence of certain voices. Cross-reference the list of people in the meeting where the decision was finalized against the list of people who commented in the RFC thread. If someone was in the meeting but not in the thread, their position on the decision is unrecorded. If that person is the most senior engineer on the team, or the person who owns the system the decision affects, their silence in the artifact is a signal. They may have agreed. They may have been overruled. You can’t tell — and that’s the problem.

The absence is the hardest signal to detect because it requires knowing who should have been in the thread. But it’s the most reliable indicator of duress. When the people who have the most context on a decision don’t appear in the written record, the written record is incomplete. The decision was made somewhere else. The document is a backfill.

§ 3 — THE REVERSE-ENGINEERED RATIONALE

Here’s what happens six months later. A new engineer — call them the inheritor — reads the ADR. They see a clean decision with a context section, alternatives, and consequences. The document reads as if the team evaluated the options and chose deliberately. The inheritor doesn’t have access to the thread. Or the thread has been archived. Or the tool has changed. Or the comments are in a Slack channel that was deleted when the workspace was reorganized. The inheritor does what engineers do: they reverse-engineer the rationale from the decision.

If the ADR says “We chose a multi-tenant architecture for long-term scalability,” the inheritor assumes the team had evidence of scaling problems. They build on that assumption. They extend the pattern. They cite the ADR in their own RFC as precedent. The original decision was made under deadline pressure by someone who didn’t know how to tune a database. The inheritor’s new decision is made under no pressure by someone who thinks they’re following a proven pattern. The fiction has become infrastructure.

This is how teams accumulate architectural decisions that nobody can explain. Not because the original decision was bad — it might have been fine under the circumstances. But because the circumstances weren’t recorded, the decision can’t be evaluated, only inherited. Every inherited decision narrows the space of what the team considers possible. And none of them can be questioned because none of them have a recorded rationale that can be examined.

The result is a codebase that feels inevitable. Why is everything multi-tenant? Because the ADR said so. Why did the ADR say so? Because that’s what we decided. The circularity is invisible because the duress that broke the circle was stripped from the record.

§ 4 — THE SAME FAILURE IN NARRATIVE PLANNING

This isn’t an engineering-only problem. Any team that maintains long-form written decision records faces the same core issue: the artifact that survives is the one that’s been cleaned up, not the one that’s true.

Consider a writing team that maintains editorial outlines — plot decisions, character arc rationales, structural choices documented for collaborators and for future reference. The same suppression pattern appears. The outline says “We chose a non-linear timeline to create thematic resonance between the two storylines.” The actual decision was made because the first draft had a pacing problem in act two and the editor suggested restructuring rather than rewriting. The outline doesn’t say that. Six months later, a collaborator reads the outline, assumes the non-linear structure was a deliberate artistic choice from the start, and builds subsequent plot decisions on top of a rationale that was never artistically intended — it was a fix that got promoted to a principle.

The Authors Guild’s guidance on writing practices emphasizes preserving the original voice, thinking, and creative reasoning that shape a work — the reasoning behind a decision is part of the work, not just the output. When editorial decision records strip that reasoning, they strip the same thing a duress-free ADR strips: the context that makes the decision legible to the next person who has to build on it.

The bridge is narrow and honest: teams that use AI novel writing software that preserves the decision trail alongside the draft face the same temptation to clean up the artifact. The tool can record the reasoning, the alternatives considered, and the disagreements — but only if the team treats the decision record as part of the work, not as paperwork to be filed after the work is done. The failure mode is identical whether the artifact is an ADR in a git repo or a narrative outline in a writing tool: the cleaned version becomes the official version, and the real context is lost.

§ 5 — ONE REVERSIBLE EXPERIMENT

For the next ADR your team writes, add a section called Decision Context — distinct from Context, which describes the technical situation. Decision Context records the conditions under which the decision was made. It answers four questions:

What deadline or pressure was active when this decision was finalized? Not the project deadline — the decision deadline. If the decision had to be made by Friday because someone was going on vacation, that’s the context. If it had to be made before a funding round, that’s the context. If there was no pressure and the team had unlimited time, write that — it’s the most important signal of all.

Who disagreed, and what was their objection? Name the objection, not the person. “An objection was raised that transaction-mode pooling would break prepared statements used by the webhook consumer. The objection was not resolved before approval.” That sentence tells the next reader everything they need to know: the decision was made with an unresolved technical concern, and the concern is specific enough to investigate.

What was the strongest argument against this decision? Not the alternatives that were considered — the strongest case for not doing it at all. If the ADR can’t articulate the best argument against itself, the ADR wasn’t written by someone who understood the tradeoff.

What would make us revisit this decision? The conditions under which the decision should be re-evaluated. Not “if requirements change” — that’s meaningless. “If the webhook service exceeds 500 connections per second, the pooling decision should be revisited because the current rationale was based on projected load of 200 cps.” That gives the inheritor a concrete test, not a vague disclaimer.

The experiment: add the Decision Context section to one ADR. Don’t mandate it for all ADRs. Don’t change the template. Don’t announce a process change. Write one ADR with the section and see what happens when the next engineer reads it. If they ask better questions about the decision, the section earned its place. If nobody reads it, you have a different problem — your ADRs aren’t being read at all, and the duress issue is downstream of a documentation culture that doesn’t exist yet.

Rollback: if the section creates friction — if people spend more time arguing about what counts as duress than making decisions — remove it. The section is a diagnostic, not a process. Its value is in what it reveals about the decision, not in its compliance as a template field. If it becomes a checkbox, it’s failed. A good Decision Context section reads like a person writing honestly about what happened. A bad one reads like a form being filled out. The difference is obvious.

§ 6 — THE ARTIFACT IS THE EVIDENCE

The ADR is not a record of what the team decided. It’s a record of what the team was willing to write down about what they decided. Those are different things. The gap between them is where the next team’s confusion lives.

When you read an ADR, read it forensically. Look for the threading depth that didn’t make it into the summary. Look for the edit that came after the last comment. Look for the approval that came too fast. Look for the voices that aren’t there. The document is telling you what happened — but it’s telling you by what it omits, not just by what it says.

And when you write one, write the duress. Write the deadline. Write the objection that wasn’t resolved. Write the argument against your own decision. The clean version is the one nobody learns from. The messy version is the one that saves the next engineer from building on a rationale that never existed.

The ADR is not a record of what the team decided. It’s a record of what the team was willing to write down about what they decided.

Every team I’ve ever audited tells me some version of the same story: everything worked fine until we grew. And that’s accurate, as far as it goes. It just isn’t a defense. A culture that only functions at one headcount isn’t culture; it’s a side effect of a small broadcast domain. Nobody lost their values when the team doubled. The hallway stopped scaling, and nothing got written down to replace it.

So treat this the way you’d treat any other scaling problem. Stop asking people how the culture feels and go read the artifacts the team already produces: git history, CI retry logs, RFC threads, incident channels, exit interview notes, career ladder docs. The failure modes have names, and you can find most of them in an afternoon. That’s the whole method on this site — pull the evidence, name the mechanism, run a reversible experiment. No trust falls required.

What an engineering culture that survives growth actually means

Definition first, because “culture” is a word that absorbs whatever meaning the speaker needs at the time. An engineering culture is the set of defaults a team follows when nobody is watching: how decisions get made, how disagreement gets resolved, how bad news travels. A culture survives growth when those defaults still work after the people who created them are no longer in every room. That’s the entire test. Not whether the offsite was fun. Whether a new hire in a satellite office, six time zones away, makes the same call the founders would have made, for reasons the founders would recognize.

Most culture programs fail this test because they treat culture as a communications problem: values documents, culture decks, all-hands talks. Those are artifacts too, and I read them, but they record intent. The git history records behavior. When the two disagree, believe the git history. They usually disagree.

Symptom: “the culture was fine until we doubled headcount”

The complaint arrives as a people problem. The evidence usually says otherwise. Here is the standard deterioration timeline, with the mechanism doing the damage at each stage.

Stage 1: Osmosis (5 to 15 engineers)

Culture travels by proximity. Every decision happens in a room where everyone is present, or in the one channel everyone reads. Corrections take seconds. This feels like a strong culture, and it is one — with a single point of failure. The failure mode is a hiring plan.

Stage 2: Folklore (15 to 40)

Decisions start getting re-litigated. Not because anyone is being difficult — because the original context lives in one person’s head, and that person is on vacation, or on another team now. A decision that has to be won twice is a retry storm with human actors: repetitive, expensive, and it ties up your most senior people every quarter.

Stage 3: Deadlock (40 to 100)

Approval chains close into loops. Team A needs B’s sign-off, B is waiting on C’s security review, C is blocked on A’s architecture decision. Nobody in that loop is doing bad work. The wait-for graph simply has a cycle in it, and the org chart is the scheduler now. Conway said it first: organizations build systems that mirror their communication paths, and the law he described cuts both ways. Fix the paths or inherit the deadlock.

Stage 4: Normalization of deviance (100 and beyond)

The flaky test gets retried until it goes green. The alert that fires 400 times a day gets muted. The postmortem gets skipped because it’s a busy week, then a busy quarter. Diane Vaughan coined normalization of deviance studying the Challenger launch decision: each small deviation gets absorbed as normal, right up until the day it isn’t. Software teams run the same pattern on a shorter fuse and call it a busy quarter.

Contributing factors, read off the evidence

A postmortem doesn’t assign blame. It lists contributing factors. These are the ones I find most often, plus the artifact that convicts each one.

• Review concentration. git shortlog -sn shows one name attached to most of the merges. That’s a bus factor of one wearing a mentorship costume.
• CI retry storms. The pipeline passes on attempt three and everyone has quietly agreed not to notice. The team has stopped trusting its own tests, and honestly, it is right not to.
• Decision debt. RFC threads that end in “let’s revisit this in Q3” instead of a decision with an owner and a date.
• Blame-shaped incident language. “Who touched this” instead of “what did we not know.” Blameless postmortems aren’t a politeness ritual — they are how you keep the people holding the information willing to talk. Google’s SRE workbook makes the case plainly in its chapter on postmortem culture.
• A career ladder made of fog. The document says “impact” forty times and defines it zero times. Promotion becomes a vibes call, and the vibes are set by whoever is loudest in the room.
• PIP spikes after reorgs. Performance improvement plans cluster three months after a reorganization. Eight people do not independently get worse at their jobs in the same quarter. Read it as the org chart failing, not the individuals.

The audit: one afternoon, six pulls

You don’t need a consultant for this. You need read access and an afternoon.

1. Git history. Run git shortlog -sn --since='6 months ago' across your repositories. Who merges, who reviews, and how concentrated is the load? There’s a longer walkthrough in my guide to reading git history for team dysfunction.
2. CI retry logs. Count pipeline runs per commit. Retry-until-green is the most honest number in your build system. I keep a fuller walkthrough on reading CI retry storms.
3. RFC threads. Find the decisions that were made and then made again. Every reopened decision is evidence that the original had no owner and no expiry date.
4. Incident channels. Search the first ten messages of your last ten incidents for the word “who.” Count the hits. That’s your blame index, and you can watch it move month over month.
5. Exit interview notes. “Compensation” is what people say when the real reason would burn a bridge. Look for what the leavers had in common: same team, same manager, same quarter. Patterns, not people. There’s a fuller method in my notes on exit interview forensics.
6. PIP timelines. Plot them against org changes. Correlation isn’t causation, but a cluster is a confession.

Action items: six reversible experiments

Each experiment below has a success signal and a rollback condition. That’s the part most culture programs skip, which is why most culture programs fail: all commit, no rollback.

1. Put expiry dates on decisions. Every significant decision gets a short record: what was decided, why, who owns it, and a revisit date. The revisit date is the trick. It ends the quarterly re-litigation, because the decision can be reopened — on schedule, by anyone, with the original context attached. Success signal: fewer reopened RFCs. Rollback: drop the practice after a quarter and see whether the retry storm comes back. It will.
2. Break approval deadlocks with a default. Take the three most-looped approvals in the org and add one rule: five working days with no substantive objection, and the owner’s call stands. A deadlock is a wait-for graph missing a timeout. Add the timeout.
3. Quarantine flaky tests instead of retrying them. A test that passes on the third attempt isn’t passing; it’s gambling. Quarantine it, make the quarantine list public, fix the test, and watch the list shrink. If the list grows instead, you’ve learned something about the team’s relationship with bad news.
4. Cap review load, then check the logs. Set a soft weekly cap on reviews per person. A month later, run git shortlog again. If the concentration didn’t move, the cap was theater, and now you know that too.
5. Rewrite the career ladder in observable behavior. Replace every “impact” and “excellence” with something you could show a stranger: designs reviewed, incidents led, decisions documented and not reopened. Ambiguity in a ladder isn’t flexibility. It’s a buffer for bias.
6. Change the exit interview question. Stop asking why they’re leaving. Ask: what did this team keep misreading about how work actually gets done? The answers get less polite and far more useful.

Misdiagnoses: what the evidence gets called instead

Every mechanism above has a personnel-shaped alias. Review concentration becomes “our senior engineer doesn’t delegate.” Decision debt becomes “we need better alignment.” Deadlock becomes “engineering is slow.” A blame index becomes “one or two bad apples.” The misdiagnosis is expensive because it triggers the wrong treatment: coaching for a structural failure, a reorg for a documentation failure, more hiring for a throughput failure. You would not rename a deadlock “insufficient ambition” and expect the process to unblock. Don’t do the equivalent to people.

What a culture that survives growth actually looks like

Boring, mostly. Decisions that stay decided until their revisit date. A CI pipeline the team trusts enough to block a release on. Incident channels that read like diagnosis instead of deposition. A career ladder a stranger could apply to real work. None of it photographs well for the about page. All of it compounds.

The test I use is simple. Can a new hire answer “how do we do this here?” by reading, without asking one specific person? If yes, the culture lives in the artifacts, and it will survive the next doubling. If no, it lives in heads, and heads are portable.

FAQ: engineering culture that survives growth

Can you measure engineering culture without a survey?

Yes, and the measurements are better, because artifacts don’t perform. Six numbers cover most of it: review concentration from git history, retry-until-green rate from CI, reopened-decision count from RFC threads, blame index from incident channels, PIP-to-reorg correlation, and the recurring pattern in exit notes. A survey tells you what people think is safe to say. The logs tell you what happened.

What’s the first artifact to pull if I only have an afternoon?

CI retry logs, then git shortlog. A team that retries its tests until they pass has already told you the feedback loop is broken and the deviance is normalized. Those two pulls take twenty minutes and usually explain half the symptoms people keep describing as interpersonal.

When should a founder stop reviewing every pull request?

Earlier than feels right. A founder review bottleneck looks like quality control right up until it becomes a hiring ceiling and a bus factor of one. If your name is on most of the merges, you aren’t raising the bar. You are the queue.

Does hiring for “culture fit” work?

It selects for sameness, which reads as harmony and behaves like monoculture. Fit-based hiring quietly builds a team that agrees with itself, which is great for lunch and terrible for incident reviews. Hire for the artifacts you want: people who write decisions down, review generously, and refuse to retry broken things until they look whole.

How long does fixing this take?

The audit is an afternoon. The experiments need about a quarter before the signals are readable. The deterioration you’re correcting took years, so a sprint won’t do it — but the first artifact pull is free, and it usually changes the very next meeting you’re in.

One last thing. Culture failure gets narrated as personal failure: the difficult engineer, the underperformer, the manager who couldn’t scale. The artifacts usually tell a different story, one where the same three mechanisms — deadlock, retry storms, normalized deviance — chew through perfectly competent people. Pull the evidence before you write the performance review. The system is confessing. Read the logs.

Most architecture documents are fiction. Not malicious fiction â nobody is lying to you on purpose â but fiction all the same: a confident narrative about a system that stopped matching reality somewhere between the approval meeting and the next reorg. The code, meanwhile, tells the truth every single day. It may be ugly, badly organized, commented in a dead language, but it is the only artifact in your company that cannot lie about what the system does. Which raises an uncomfortable question about why we keep producing forty-page PDFs describing it.

I have read a lot of these documents. In postmortems, in onboarding folders, in the quiet despair of a wiki nobody visits. The worst one I owned described a payments queue that was decommissioned before I was hired; two cohorts of new engineers learned about a service that never existed. The pattern is consistent enough to be boring: the document is a snapshot of intent, taken at the moment the author needed approval, and never updated again. Everything after that snapshot is a story the code writes without the author.

The document has no write path

State the core mechanic bluntly: code has a write path, and documents don’t. Code gets merged several times a day. Every pull request, every hotfix, every 2 a.m. hack rewrites the source of truth. The document’s write path ran exactly once, on approval day, and was then decommissioned. What you are left holding is a cache entry with no TTL, no expiry check, and no owner. It serves stale data with total confidence until somebody trusts it at the worst possible moment.

This is a race condition between two artifacts that are supposed to agree. One commits a hundred times a week. The other last wrote to disk in 2022. Guess which one wins.

Nobody notices, because nothing depends on the document. Dead code at least gets flagged by a linter or deleted in a cleanup sprint. Dead documents get bookmarked. They sit in the onboarding folder with the institutional equivalent of a verified badge: a senior engineer linked to it once, so it must be true.

What the document actually records

Read a stale architecture document carefully and you notice it was never really about the system. It is about the meeting. It records what the author needed to say to get the design through review: the tradeoffs that convinced the room, the boxes that looked tidy on a slide, the org chart as it existed that quarter. A transcript of a social ritual, typeset in a diagramming tool.

This is why reorgs kill these documents so reliably. The doc captures Conway’s law as it stood at approval time. Two reorgs later, the platform team it references has been split, merged, renamed, and split again. The document is now alternate-history fiction about an organization that no longer exists, while the actual system has quietly reshaped itself around the new org, with nobody writing any of it down. It has become a legacy system without the one decency legacy systems offer, which is that they still run.

Four operational signals your docs are fiction

You don’t have to audit the wiki to diagnose this. Like most organizational failures, stale documentation shows up in operational exhaust â the signals your team produces anyway, without meaning to. Four of them, roughly in the order they surface.

New hires route their questions around the documentation

Watch where a new engineer’s questions actually go. If the onboarding doc were load-bearing, the questions would thin out after week two. They don’t. They route to the same two senior engineers, every cohort, forever: âwho owns this service,â âwhy is there a second checkout path,â âis that diagram current.â The last one is the tell. When people ask whether a document is true before they are willing to read it, the document has already failed. Those two seniors are doing the documentation’s job by hand, in interrupt-driven mode. If you want the longer version: onboarding questions are a systems signal, not a people problem.

During incidents, nobody opens the doc

Incident response is documentation’s honesty test. At 2 a.m. with a customer-facing outage, people reach for whatever has the shortest path to the truth: dashboards, logs, git blame, the person who wrote the code. If the architecture overview or the runbook gets opened at all, watch what happens next. Do responders act on it, or do they open it, grimace, and keep scrolling? Opening a stale runbook mid-incident is a blocking call that returns the wrong answer and charges you for the latency. It burns the one resource you cannot recover mid-incident: attention.

Doc edit dates lag code churn by years

This one you can measure in an afternoon. Take your five most-linked documents and compare the last substantive edit date against the commit rate of the services they describe. A document last touched in March, describing a service that has taken four hundred commits since, is fiction with a header image. The gap between those two numbers is your documentation debt. Unlike technical debt, nobody has built a dashboard for it, so it compounds quietly.

A recurring meeting exists to explain the architecture

The monthly architecture walkthrough is not a knowledge-sharing initiative. It is a compensating control for a dead write path. The system’s description lives in one person’s head, and the meeting is the cron job that re-renders it for an audience. It works, mostly, the way manual retry loops work â until the person with the architecture in their head is on vacation during an incident and everyone discovers the wiki page was a placeholder. Recurring meetings are compensating controls more often than anyone admits; this is one of the textbook cases.

Root cause: the document’s only consumer was the approval

Run this like a postmortem and the root cause is almost embarrassingly simple. Architecture documents are approval artifacts. Their entire consumer base is one meeting that happens once. After approval, the document has no readers with the power to change it, no owner accountable for it, and no trigger that fires when the system it describes gets rewritten. A component with no consumers, no owner, and no alerts doesn’t stay accurate out of spite. It rots, the way anything unowned rots.

Contributing factors, in the usual style: updating the doc helps a future teammate nobody has met, while skipping it costs nothing today. The author has since moved to another team, where they are currently writing a new document that will also be true for about six weeks. And nothing in any feedback loop â the review, the retro, the ops review â notices the gap, because the gap has no metric. This is not a character flaw. Teams skip documentation maintenance for the same reason they skip any maintenance: unowned things rot, and nobody gets paged when they do.

What a document is actually worth

The what belongs to the code. The why is the only thing worth writing down. Code answers what the system does with total fidelity and zero context. It can’t tell you why the alternative was rejected, which invariants are load-bearing and which behaviors are incidental scar tissue from a 2019 incident, or which parts of the design are deliberate and which are leftovers nobody dared to delete. That information exists in exactly three places: the heads of people who were there, old pull request threads, and nowhere. Documents that capture the why survive contact with change. Documents that duplicate the what get outcompeted by git blame and die quietly.

So the fix is not âupdate the wiki more,â whatever the consultant deck says. The fix is to stop writing documents that describe the system and start writing documents that record decisions.

Architecture decision records are the boring, durable version of this. One page per decision: context, options considered, what we chose, what we expect to regret. Michael Nygard’s short 2011 note on documenting architecture decisions is still the best thing written on the subject, and it is shorter than most design review agendas. Each record is immutable, so it cannot drift â it can only be superseded by a newer record, which leaves a visible trail. You get a git history for reasoning instead of a PDF that gets quietly rewritten until it means nothing.

For the parts that genuinely need describing â system context, trust boundaries â keep it small. Simon Brown’s C4 model is the sane version: one context diagram, maybe one container diagram, then stop. Anything more detailed is a re-implementation of the codebase in a diagramming tool, and the codebase wins that race every time, because it has a write path and the drawing doesn’t. Google’s public write-up of its design doc practice lands the same point from the other end: the document exists to align people and record reasoning, not to mirror the code.

If you insist on keeping documents, treat them like systems

Short list, deliberately. Everything on it is a mechanism, not an exhortation.

• Every document gets an owner and a last-reviewed date. In the header, not in metadata nobody renders. A page without those two fields is an unowned service, and you already know what happens to those.
• Somebody owns the kill switch. When a pull request moves a trust boundary or splits a service, the review checklist asks which document it just made wrong. One question, asked at the moment the ground truth moves.
• Supersede, don’t edit. Rewriting history inside a doc is how you get fiction with a fresh timestamp. Mark the old decision superseded and link the new one.
• Review docs where you review ops. The quarterly review that already looks at deployment frequency and incident load can spend ten minutes on documentation freshness. Same lens, same meeting, no new ritual.
• Delete more than you update. A dead document that admits it is dead is harmless. A dead document with confidence is the expensive one.

Frequently Asked Questions

Why do architecture documents become fiction so quickly?

Because their write path runs exactly once, at approval, while the code they describe commits daily. With no owner, no expiry trigger, and no review cadence, every document starts drifting the moment the first post-approval pull request lands. It isn’t carelessness. It is a system with no feedback loop.

What should an architecture document contain instead of system descriptions?

Decisions, rejected alternatives, invariants, and constraints â the why the code cannot express. Record what you chose, what you turned down, and what you expect to regret. Topology, sequence flows, and component inventories belong to the code, or to diagrams you can re-render from it. Anything maintained by hand that a repository can tell you is a second source of truth, and second sources of truth always diverge.

How can I tell if my team’s documentation is fiction?

Check the operational signals before reading a word: where new hires route their questions, whether incident responders open the runbook and act on it, the gap between each document’s last edit date and the commit rate of the services it describes, and whether a recurring meeting exists to explain the architecture the docs were supposed to cover. If two or more of those look bad, the docs are fiction regardless of how good the prose is.

Are architecture decision records worth the overhead?

Yes, mostly because the overhead is one page per decision and the alternative is expensive. The cost lands at the moment you are already thinking hard about the decision anyway. The payoff shows up years later, when somebody asks why the system looks like this and the answer is a document instead of an archaeology dig through closed pull requests and whoever is still around to remember.

The uncomfortable summary

Your architecture document was a true story once, on the afternoon it was approved. Everything since has been the code changing and the document declining to notice. Stop asking teams to maintain descriptions the code maintains better, and spend the writing effort where the code cannot go: decisions, rejections, reasons. That part earns its bytes. The rest was always worth less than the code, and pretending otherwise is how the wiki got this bad.

Code review is a control point. It’s where an organization decides whether knowledge moves through the system or gets queued behind a senior engineer’s preferences. The difference between mentoring and gatekeeping isn’t intent. It shows up in review latency, comment density, approval patterns, and the number of times a diff gets bounced for reasons that were never in the ticket. If your team treats code review as a quality gate, you have a process. If your team treats it as a teaching interface, you have a system. Most teams have neither. They have a blocking call wrapped in politeness.

This article is for senior ICs and engineering managers who suspect their team’s dysfunctions are system failures, not personal failings. We’ll look at code review as an operational signal: what it reveals about knowledge distribution, decision rights, and the actual cost of “just one more nit.” The goal isn’t to make code review nicer. The goal is to make it legible.

Code Review as a System, Not a Conversation

When a pull request sits for three days, that’s not a conversation. That’s a queueing delay. When a reviewer leaves forty comments on a two-hundred-line diff, that’s not thoroughness. That’s a batch process with no service-level objective. When the same two people approve every critical path change, that’s not expertise. That’s a single point of failure with a bus factor of one.

Operational signals from code review are easy to collect and almost never collected. Review latency, first-response time, comment-to-merge ratio, rework cycles, approval depth, and the distribution of reviews across the team. These numbers will tell you more about your team’s sociology than any retro. A team where reviews are fast, shallow, and widely distributed is a team that trusts its tests and its onboarding. A team where reviews are slow, deep, and concentrated is a team that has institutionalized distrust and called it quality.

Mentoring through code review means the reviewer’s primary output is a more capable author. Gatekeeping means the reviewer’s primary output is a merged diff that matches their mental model. Both can produce working code. Only one produces a team that can survive the reviewer’s vacation.

The Latency Signal: Blocking Calls and Starvation

In distributed systems, a blocking call is one that stops the caller until the callee returns. Code review is a blocking call in the development pipeline. The author can’t merge until the reviewer responds. If the reviewer is overloaded, the author starves. If the author is junior, the starvation is worse, because they have fewer alternative tasks and less political capital to escalate.

Review latency is the single most honest metric in engineering culture. It tells you whose time the organization values. A team that measures cycle time but not review latency is optimizing the wrong variable. A team that celebrates “fast merges” while two senior engineers hold a de facto veto is running a race condition: the system appears fast until the critical section is contended, and then everything stops.

Mentoring systems set expectations for review latency. They treat a stale review as an incident, not a personality trait. Gatekeeping systems treat latency as a feature: the longer the wait, the more the author learns to write code that won’t get comments. That’s not learning. That’s avoidance training.

Comment Density and the Nitpick Tax

Every comment on a code review has a cost. The author must read it, respond to it, and often change the code. The reviewer must re-review. The team must wait. A comment that catches a real bug is worth that cost. A comment that renames a variable to match the reviewer’s taste is a tax. A comment that asks a question already answered in the ticket is a tax with interest.

Mentoring reviewers separate blocking comments from non-blocking comments. They use prefixes like “nit:” or “optional:” and they mean it. They don’t leave twenty nits on a diff and then approve it, because that teaches the author that nits are noise. Gatekeeping reviewers leave twenty nits and request changes, because the nits aren’t about the code. They’re about the reviewer’s need to be the smartest person in the thread.

There’s a simple test. If you removed every comment that could be fixed by a linter, a formatter, or a style guide, how many comments remain? If the answer is close to zero, your code review process is a style enforcement mechanism, not a quality mechanism. You have automated nothing and called it rigor.

Approval Patterns and the Bus Factor

Look at the last fifty merged pull requests. Count how many were approved by each engineer. If the distribution is roughly uniform, you have a healthy review culture. If two engineers account for eighty percent of approvals, you have a gatekeeping system, even if those engineers are kind, patient, and well-intentioned.

Concentrated approval power is a legacy system. It works until the key person leaves, burns out, or becomes a bottleneck. Then the team discovers that nobody else knows how to review a database migration, because nobody else was ever allowed to. The knowledge was never transferred. It was rented.

Mentoring systems deliberately rotate reviewers. They pair a senior engineer with a mid-level engineer on the same review. They let a junior engineer approve a trivial change and then discuss the decision in a follow-up. They treat review authority as a skill to be distributed, not a privilege to be hoarded. Gatekeeping systems treat review authority as a credential. The credential is never explained, never tested, and never revoked.

Rework Cycles and the Hidden Curriculum

A rework cycle is when a pull request is sent back to the author for changes. One rework cycle is normal. Two is a conversation. Three or more is a failure of the review process, not the author. Either the requirements were unclear, the reviewer changed their mind, or the reviewer is using the diff as a drafting table for their own design preferences.

Rework cycles are where gatekeeping hides. A gatekeeper will request changes, then request more changes, then request a rebase, then request a test that was never in the acceptance criteria. Each cycle looks reasonable in isolation. The pattern is the signal. The author isn’t learning to write better code. They’re learning to predict the reviewer’s mood.

Mentoring systems cap rework cycles. They say, explicitly, “If this diff needs more than two rounds, we’ll schedule a synchronous conversation.” That conversation is where the actual knowledge transfer happens. The code review was never the right medium for a design debate. It’s a diff, not a whiteboard.

Documentation Freshness as a Review Artifact

Code review isn’t just about the code. It’s about the decisions that produced the code. A healthy review process leaves artifacts: updated runbooks, revised ADRs, clarified ticket descriptions, new tests that encode a previously implicit assumption. An unhealthy review process leaves only the diff and a trail of comments that will never be read again.

Mentoring reviewers ask, “What should we write down so the next person doesn’t have to ask?” Gatekeeping reviewers ask, “Why didn’t you already know this?” The first question creates documentation. The second question creates silence.

If your team’s documentation is stale, look at your code review culture. Teams that treat review as a teaching interface update their docs as a side effect. Teams that treat review as a quality gate let the docs rot, because the gate only checks the code, not the context around it.

Incident Response Patterns and Review Culture

There’s a direct line between code review culture and incident response. Teams with gatekeeping reviews tend to have blame-oriented postmortems. The same people who hold the approval power also hold the retrospective microphone. The incident is framed as a failure of the author, not a failure of the review system that let the bug through.

Teams with mentoring reviews tend to have blameless postmortems, because the review process already distributes responsibility. If a bug ships, the question isn’t “Who wrote this?” but “What signal did we miss in review, and why was the review not structured to catch it?” That’s a system question. It leads to better tests, better runbooks, and better review checklists. It doesn’t lead to a scapegoat.

Watch how your team reacts to a production incident. If the first question is “Who approved this?” you have a gatekeeping culture. If the first question is “What did we not know?” you have a mentoring culture. The code review process is the upstream cause of that downstream behavior.

Meeting and Decision Artifacts

Code review is a decision-making process. Every approval is a decision. Every request for changes is a decision. Every stale review is a decision, even if it’s a decision by omission. Teams that understand this keep decision artifacts: design docs, ADRs, review checklists, and explicit definitions of done. Teams that don’t understand this keep only the diff and a vague memory of “we talked about it in standup.”

Mentoring systems make decisions legible. They write down why a particular pattern was chosen, why a particular library was rejected, why a particular test was considered sufficient. Gatekeeping systems keep decisions in the reviewer’s head. The author is expected to absorb the decisions through repeated rejections. That’s not mentoring. That’s hazing with extra steps.

If you want to know whether your team is mentoring or gatekeeping, ask a new engineer to explain why a particular code review comment was made six months ago. If they can find the answer in a doc, you have a mentoring system. If they have to ask the person who wrote the comment, you have a gatekeeping system with a bus factor of one.

Operational Signals Checklist

Here’s a concrete checklist for diagnosing your team’s code review culture. Each item is an operational signal, not a personality judgment.

• Review latency: Median time from PR open to first review. If it exceeds your team’s stated expectation, the system is broken.
• Comment-to-merge ratio: Total review comments divided by merged PRs. A high ratio with low rework means nits are noise. A high ratio with high rework means the review is a design forum.
• Approval distribution: Percentage of PRs approved by each engineer. A concentration above fifty percent for any single engineer is a bottleneck.
• Rework cycles: Number of PRs with three or more review rounds. If this number is rising, the review process is failing to transfer knowledge.
• Documentation freshness: Percentage of review comments that result in a doc update. If it’s near zero, the review isn’t creating durable knowledge.
• Incident follow-up: Percentage of postmortems that reference a review gap. If it’s near zero, the review process isn’t being treated as a system.

Collect these numbers for two weeks. Don’t announce a new policy. Just observe. The pattern will tell you whether your team is mentoring or gatekeeping, and it will tell you without a single awkward conversation about feelings.

What Mentoring Actually Looks Like in a Diff

Mentoring through code review isn’t about being nice. It’s about being specific, timely, and willing to let go. A mentoring reviewer does the following:

• Responds within the team’s agreed latency window, or explicitly hands off the review.
• Separates blocking issues from non-blocking nits, and uses a consistent prefix system.
• Explains the “why” behind a comment at least once, then links to the doc on subsequent occurrences.
• Approves the diff when the blocking issues are resolved, even if they would have written it differently.
• Offers to pair on the change if the diff needs more than two rework cycles.
• Updates the relevant doc or ADR when a review reveals a gap in shared knowledge.

None of this requires charisma. It requires discipline. The discipline to treat review as a system with inputs, outputs, and service-level objectives. The discipline to measure the system instead of blaming the people in it.

What Gatekeeping Actually Looks Like in a Diff

Gatekeeping isn’t always loud. It’s often quiet, patient, and dressed in the language of quality. A gatekeeping reviewer does the following:

• Leaves the PR unread for days, then requests changes on a deadline.
• Leaves comments that are really questions about the author’s competence, not the code.
• Requests changes on style preferences that aren’t in the team’s style guide.
• Approves only after the author has rewritten the diff to match the reviewer’s personal architecture.
• Never approves a diff from a junior engineer without a second senior sign-off, even for trivial changes.
• Treats every review as a chance to demonstrate expertise, not to build it in others.

The gatekeeper’s defense is always the same: “I’m just maintaining quality.” But quality is a system property, not a personal property. A system that depends on one person’s vigilance isn’t a quality system. It’s a single point of failure with a hero complex.

The Cost of Gatekeeping

Gatekeeping has measurable costs. It slows cycle time, which delays value delivery. It concentrates knowledge, which increases bus factor. It discourages junior engineers, which increases turnover. It creates a culture of learned helplessness, where authors stop thinking and start guessing what the reviewer wants. It turns code review from a learning loop into a compliance ritual.

The cost isn’t just emotional. It shows up in deployment frequency, incident rates, and onboarding time. A team with a gatekeeping review culture will deploy less often, because every deploy requires a blessing. It will have more incidents, because the review process is optimized for style, not correctness. It will take longer to onboard new engineers, because the only way to learn the unwritten rules is to violate them and get rejected.

If you’re an engineering manager, these costs are on your budget. If you’re a senior IC, these costs are on your calendar. Either way, they’re not abstract. They’re the reason your team feels slow, brittle, and afraid to ship.

How to Shift from Gatekeeping to Mentoring

The shift doesn’t require a cultural transformation program. It requires three operational changes.

First, make review latency visible. Add a dashboard or a bot that reports median review latency per engineer. Don’t use it to shame people. Use it to start a conversation about capacity. A reviewer who takes three days to respond is either overloaded or disengaged. Both are system problems, not personality problems.

Second, separate blocking and non-blocking comments. Adopt a prefix convention and enforce it in the review tool. If a comment isn’t blocking, it shouldn’t block the merge. If a reviewer wants to block on a style preference, they must first get that preference into the style guide. That single rule eliminates most gatekeeping behavior, because it forces preferences to become policy or disappear.

Third, rotate review authority. Every engineer above a certain level should be able to approve any diff in their area. Pair senior reviewers with mid-level reviewers for a quarter. Let junior engineers approve trivial changes and then review their approvals in a weekly sync. The goal is to distribute the bus factor, not to lower the quality bar. Quality will improve, because more people will understand why the bar exists.

These changes aren’t expensive. They aren’t risky. They’re just boring operational work. That’s why most teams don’t do them. Boring operational work is the difference between a system that runs and a system that limps.

FAQ

How do I tell if a code review comment is mentoring or gatekeeping?

Look at the comment’s effect on the author’s future behavior. A mentoring comment teaches a principle that applies beyond the current diff. A gatekeeping comment enforces a preference that applies only to the current reviewer. If the comment could be replaced by a linter rule or a style guide entry, it’s gatekeeping. If it explains a tradeoff or a system constraint, it’s mentoring.

What is a healthy code review latency for a team?

There’s no universal number, but a useful baseline is same-day first response for PRs under 400 lines, and 24 hours for larger changes. The key isn’t the absolute number but the consistency. A team that reviews in two hours on Monday and three days on Thursday has a capacity problem, not a latency problem. Measure the distribution, not just the median.

Can a senior engineer be a gatekeeper without realizing it?

Yes. Most gatekeeping isn’t malicious. It’s the natural behavior of an expert who has internalized a set of rules and forgotten that those rules were never written down. The expert experiences their preferences as objective quality standards. The junior engineer experiences them as arbitrary rejections. The fix isn’t to blame the expert but to externalize the rules: write them down, agree on them, and let the linter enforce them.

How does code review culture affect incident response?

Code review culture sets the default for how the team assigns responsibility. A gatekeeping culture assigns responsibility to individuals: the author who wrote the bug, the reviewer who missed it. A mentoring culture assigns responsibility to systems: the review checklist that lacked a security check, the test suite that lacked a regression case. Blameless postmortems are only possible in a mentoring culture, because the team has already practiced asking system questions instead of person questions.

The next time you open a pull request, look at the review thread not as a conversation but as a log file. The latency, the comment density, the approval pattern, the rework cycles. That log file is telling you whether your team is building engineers or building bottlenecks. The difference isn’t in the code. It’s in the system around the code.

Every senior engineer has stood in front of a codebase and felt the pull. The pull says: burn it down. The pull says: this is not a system, it is a sediment deposit. The pull says: if I could just start over, I would do it right this time. That pull is not a technical signal. It is an emotional one. And it is usually wrong.

This article is about separating two very different failure modes. The first is a codebase that has accumulated enough structural debt that a rewrite is the rational economic choice. The second is a team that has accumulated enough operational debt that a rewrite is the rational emotional choice — a way to avoid confronting the team’s own dysfunctions. The two look identical from the inside. They are not identical. The difference shows up in deployment frequency, code review latency, incident response patterns, documentation freshness, and meeting artifacts. Those are the operational signals. Learn to read them before you touch the code.

I am Fritz Muller. I write about engineering team sociology and operational culture critique for senior ICs and EMs who suspect their team’s dysfunctions are system failures, not personal failings. This is not a guide to refactoring. It is a guide to diagnosing the system before you let the system diagnose you.

The Rewrite Impulse Is a Blocking Call

In software, a blocking call is a function that stops the entire program while it waits for something external. A database query. A network response. A file read. The program cannot proceed until the call returns. The rewrite impulse works the same way. It blocks the team’s ability to make incremental progress because everyone is waiting for the new system to arrive. The old system is frozen. The new system is not ready. Nothing ships.

Teams that want a rewrite tend to exhibit a specific operational pattern: deployment frequency drops before the rewrite is even announced. The team stops fixing the old system because they believe it is temporary. They stop writing tests for it. They stop documenting it. They stop reviewing its pull requests with any seriousness. The old system becomes a zombie: still running, still serving traffic, but no longer receiving meaningful investment. The team has already mentally moved on. The codebase has not.

This is not a technical signal. It is a cultural one. The team has decided the old system is dead, so they treat it as dead. The codebase did not ask for that. The team did.

Operational Signal: Deployment Frequency

Look at the deployment history for the last six months. If the team is still shipping to the old system at a steady cadence — even small fixes, even boring maintenance — the codebase is not telling you it needs a rewrite. It is telling you it needs maintenance. A codebase that truly needs a rewrite will show a different pattern: deployments are frequent but increasingly risky. Each release requires more rollback planning. Each release touches more files. Each release has a longer stabilization period. The cost of change is rising, not because the team is lazy, but because the system’s internal structure has degraded to the point where every change is a cross-cutting concern.

If deployments are infrequent because the team has stopped trying, that is a team problem. If deployments are frequent but each one is a small crisis, that is a codebase problem. The distinction matters.

Code Review Latency as a Cultural Thermometer

Code review latency is one of the most underrated operational signals in software organizations. It measures the time between a pull request being opened and the first meaningful review comment. Not the first emoji. Not the first “LGTM”. The first comment that engages with the actual change.

Teams that want a rewrite show a specific latency pattern: reviews on the old codebase slow to a crawl, while reviews on any new prototype or spike are nearly instant. The team is not busy. The team is disengaged. They are voting with their attention. The old codebase has become a chore, and the new codebase — even if it is just a README and a dream — is exciting. This is not a technical signal. It is a motivation signal.

A codebase that needs a rewrite will show a different pattern: reviews are slow because every change is genuinely hard to evaluate. The diff is large. The blast radius is unclear. The tests are flaky. Reviewers are not disengaged; they are overwhelmed. They ask questions like “what does this break?” and “is there a simpler way?” and “why is this file even in this module?” Those are technical questions. The disengaged team asks no questions at all.

Operational Signal: Review Comment Depth

Measure the average length of review comments on the old codebase over the last three months. If comments have become shorter, more generic, or more deferential — “looks fine to me”, “not my area”, “ship it if you want” — the team has checked out. If comments are still substantive but increasingly negative — “this will break the payment flow”, “we tried this in 2019 and it caused a data loss incident”, “this module is a tangle and I cannot verify this change is safe” — the codebase is the problem. The team is still engaged. The system is not cooperating.

Incident Response Patterns: The Most Honest Signal

Incidents are the closest thing software organizations have to a stress test. They reveal what the team actually believes about the system, not what they say in planning meetings. A team that wants a rewrite will respond to incidents in the old system with a specific pattern: resignation. The incident is treated as inevitable. The postmortem is perfunctory. The action items are vague. The underlying tone is “of course this broke, the whole thing is garbage, we need to rewrite it.”

A codebase that needs a rewrite will produce a different incident pattern: surprise. The team is genuinely shocked that the system failed in this particular way. The postmortem is detailed. The action items are specific. The underlying tone is “we did not see this coming, and we need to understand why.” That is a team that still believes the system can be understood. That belief is the difference between a maintenance problem and a rewrite problem.

Watch for the phrase “known issue” in incident channels. If the team has a long list of known issues that they have accepted as permanent, that is a team that has given up. If the team has a long list of known issues that they are actively triaging and fixing, that is a team that is managing a difficult codebase. The list is the same. The response is not.

Operational Signal: Postmortem Action Item Completion

Track the completion rate of postmortem action items over the last year. Teams that want a rewrite will have a low completion rate on action items related to the old system. Not because the items are hard, but because the team does not see the point. Teams that are managing a codebase that needs a rewrite will have a higher completion rate, but the items themselves will be increasingly defensive: adding more monitoring, adding more guards, adding more tests around fragile areas. The team is not fixing the root cause because the root cause is structural. But they are still trying to contain the damage. That is the signature of a codebase problem.

Documentation Freshness: The Canary in the Coal Mine

Documentation is the first thing to die when a team disengages. Not because documentation is hard, but because documentation is an act of faith. Writing documentation says: this system will still be here in six months, and someone will need to understand it. A team that wants a rewrite stops writing documentation because they no longer believe the system will be here in six months. The documentation becomes a fossil record of a previous era.

Look at the last-modified dates on the core documentation. If the architecture docs, the runbooks, and the onboarding guides have not been meaningfully updated in six months or more, that is a signal. But it is an ambiguous signal. A codebase that needs a rewrite will also have stale documentation, because the system changes faster than anyone can document it. The difference is in the attempts. A team managing a difficult codebase will have a trail of half-finished documentation updates, abandoned because the system changed again. A team that wants a rewrite will have no trail at all. They stopped trying.

Operational Signal: Documentation Commit History

Check the git history for the docs directory. If there are no commits in the last quarter, that is a team signal. If there are commits but they are increasingly out of date within weeks, that is a codebase signal. The first means the team has stopped caring. The second means the system is changing too fast to document. Both are problems. Only one is solved by a rewrite.

Meeting and Decision Artifacts: The Paper Trail of Intent

Meetings are where teams negotiate their relationship with the codebase. The artifacts of those meetings — decision records, architecture review notes, planning docs — are a paper trail of intent. A team that wants a rewrite will have a specific pattern in their meeting artifacts: the rewrite is discussed as a foregone conclusion, not as a decision. The architecture review notes will say things like “when we rewrite this” not “if we rewrite this”. The planning docs will have a section called “post-rewrite” with no criteria for what would trigger the rewrite in the first place. The decision record, if it exists at all, will be thin.

A codebase that needs a rewrite will have a different pattern: the rewrite is discussed as a reluctant conclusion, reached after exhausting alternatives. The decision record will be long. It will list the alternatives that were tried. It will list the metrics that were measured. It will list the specific failure modes that made incremental improvement impossible. The team did not want to rewrite. The codebase forced them to.

This is the single most reliable signal I know. A team that wants a rewrite will not have a decision record. A codebase that needs a rewrite will have a decision record that reads like a eulogy.

The Race Condition Between Team and Codebase

In concurrent programming, a race condition occurs when two processes access shared state and the outcome depends on the order of execution. The team and the codebase are in a race condition. The team’s motivation and the codebase’s structure are both changing, and the outcome depends on which one degrades first.

If the team’s motivation degrades first, the codebase will look worse than it is. The team will stop maintaining it, stop documenting it, stop reviewing it, and stop responding to its incidents with any seriousness. The codebase will then actually get worse, because neglect is a self-fulfilling prophecy. The team will point to the degraded codebase as proof that they needed a rewrite all along. They are right, but only because they caused it.

If the codebase’s structure degrades first, the team’s motivation will follow. The team will try to maintain it, try to document it, try to review it, and try to respond to its incidents. But the system will resist. Every change will be harder than the last. Every incident will be more surprising. The team will eventually conclude that a rewrite is necessary. They are right, and they have the decision record to prove it.

The question is not “does this codebase need a rewrite?” The question is “which degraded first?” The answer is in the operational signals.

A Diagnostic Checklist for Senior ICs and EMs

Here is a practical checklist. Run it before you run the rewrite.

• Deployment frequency: Is the team still shipping to the old system? If yes, is each deployment a small crisis? If no, why did they stop?
• Code review latency: Are reviews slow because the team is disengaged, or because the changes are genuinely hard to evaluate?
• Incident response: Are incidents met with resignation or surprise? Are postmortem action items completed?
• Documentation freshness: Is the documentation stale because the team stopped trying, or because the system changes too fast to document?
• Decision artifacts: Is there a decision record for the rewrite? Is it long and reluctant, or thin and eager?

If the answers point to team disengagement, a rewrite will not fix the problem. It will just move the disengagement to a new codebase. The team will be excited for three months, and then the same patterns will reappear. The new codebase will become the old codebase. The rewrite will have been a very expensive team-building exercise.

If the answers point to structural degradation, a rewrite may be the right call. But it should be a decision, not a mood. It should have a decision record. It should have success criteria. It should have a plan for the old system during the transition. And it should be led by people who understand that a rewrite is a system migration, not a fresh start. There is no fresh start. There is only a new system with a new set of problems.

What to Do Instead of Rewriting

If the diagnosis is team disengagement, the fix is not technical. It is operational. Here are three concrete moves.

First, force a deployment. Pick a small, boring fix in the old system and ship it. Not a feature. A fix. A typo in an error message. A log line that is too noisy. A test that is flaky. Ship it. The act of shipping to the old system breaks the mental block. It reminds the team that the old system is still a system, not a corpse.

Second, write a decision record for the rewrite. Not a plan. A decision record. What problem are we solving? What alternatives have we tried? What metrics would tell us the rewrite is working? If the team cannot write this document, they do not have a case for a rewrite. They have a feeling. Feelings are not a basis for a multi-quarter engineering investment.

Third, rotate the on-call burden. Disengagement often concentrates in the people who carry the pager. They are the ones who feel the old system’s pain most acutely. They are the ones who want to burn it down. Rotate the on-call schedule so that the people who want the rewrite are not the only ones feeling the pain. The pain will either spread, which will create a real case for change, or it will dissipate, which will reveal that the pain was localized, not systemic.

When the Codebase Is Actually Right

Sometimes the codebase is right. Sometimes the system has accumulated so much structural debt that incremental improvement is genuinely impossible. The signs are specific. The module boundaries have collapsed. The data model is wrong in a way that cannot be fixed without a migration that is itself a rewrite. The test suite takes longer to run than the code takes to write. The deployment process is a manual ritual that only one person understands. The incident rate is rising, and each incident is a new failure mode, not a repeat of an old one.

When these signs are present, the rewrite is not an emotional escape. It is an economic necessity. The cost of maintaining the old system exceeds the cost of building a new one. The team is not running away from the old system. They are running toward a system that can actually support the business.

But even then, the rewrite should be a decision, not a mood. It should have a decision record. It should have a plan. It should have a team that understands the old system well enough to know what to preserve. A rewrite led by people who hate the old system will produce a new system that repeats the old system’s mistakes. A rewrite led by people who understand the old system will produce a new system that learns from them.

FAQ

How do I know if my team’s desire for a rewrite is legitimate?

Look for a decision record. A legitimate rewrite desire is accompanied by a written document that lists the alternatives tried, the metrics measured, and the specific failure modes that made incremental improvement impossible. If no such document exists, the desire is a mood, not a decision. Moods are not a basis for a multi-quarter engineering investment.

What is the single most reliable operational signal that a team wants a rewrite rather than needs one?

Deployment frequency. If the team has stopped shipping to the old system before the rewrite is even announced, that is a team signal. The team has mentally moved on. The codebase did not ask for that. The team did. A codebase that needs a rewrite will show frequent but increasingly risky deployments, not a sudden stop.

Can a rewrite fix a disengaged team?

No. A rewrite can temporarily re-engage a disengaged team, but the disengagement will return. The underlying operational patterns — slow reviews, stale documentation, perfunctory postmortems — are team behaviors, not codebase properties. They will follow the team to the new codebase. Fix the team’s operational culture first. Then decide if the rewrite is still necessary.

What should I do if I am a senior IC and my EM is pushing for a rewrite I think is unnecessary?

Ask for the decision record. Ask what alternatives have been tried. Ask what metrics would tell you the rewrite is working. Ask what happens to the old system during the transition. If the EM cannot answer these questions, the rewrite is a mood. Your job is not to block the rewrite. Your job is to force it to become a decision. That is the most useful thing a senior IC can do.

This article is part of a series on reading operational signals in engineering teams. The next article will cover how to diagnose a team that has stopped reviewing code — not because they are busy, but because they have stopped caring. If you have a team signal you want diagnosed, send it in. I read everything.

Uptime is a vanity metric. It tells you the system stayed up, but it says nothing about how your team behaves when the system goes down. The incident postmortem process—the written record of what broke, who noticed, how long it took to diagnose, and what changed afterward—is a far better signal of engineering health. It captures decision latency, blame distribution, documentation quality, and whether your team treats failure as a learning loop or a PR exercise. If you are a senior IC or EM who suspects your team’s dysfunctions are system failures, not personal failings, start reading postmortems like operational telemetry.

This article is for engineers and managers who have sat through a postmortem that felt like a performance review. You know the one: the timeline is vague, the action items are assigned to the person who made the mistake, and the phrase “root cause” is used as a full stop instead of a starting point. We will diagnose what your postmortem process actually measures, why it beats uptime as a metric, and how to read the hidden patterns in your own incident write-ups.

The Postmortem as a System Diagnostic

A postmortem is not a document. It is a snapshot of your team’s operational nervous system. The way you write it, review it, and act on it reveals more about your engineering culture than any dashboard. Uptime is a lagging indicator of infrastructure stability. Postmortem quality is a leading indicator of team adaptability.

Consider two teams with identical uptime: 99.95%. Team A runs a postmortem within 24 hours of every incident, writes a blame-free timeline, and tracks action items to completion. Team B waits a week, produces a two-paragraph summary, and assigns a single owner to “fix the process.” Same uptime. Different futures. Team A is building a system that learns. Team B is building a system that repeats.

The postmortem process is a better metric because it measures the recovery loop, not just the failure event. Uptime tells you the system was available. Postmortems tell you whether your team can improve availability without heroics, whether incidents trigger systemic fixes or individual apologies, and whether your on-call rotation is a learning environment or a burnout factory.

What Your Postmortem Actually Measures

When you read a postmortem, you are reading a compressed history of your team’s decision-making. Here are the operational signals hidden in the document:

• Time to detection: How long did it take to notice the incident? If detection relies on a customer complaint, your monitoring is a legacy system with no active maintainers.
• Time to diagnosis: How long from detection to understanding the failure mode? Long diagnosis times often mean your system has undocumented coupling—a race condition in your architecture that no single engineer can hold in their head.
• Blame language: Does the postmortem say “the engineer pushed a bad config” or “the deploy pipeline allowed an invalid config to reach production”? The first is a personal failing. The second is a system failure. Your postmortem vocabulary is a direct readout of your team’s psychological safety.
• Action item specificity: Are action items like “improve monitoring” or “add a check for empty arrays in the payment service”? Vague action items are a blocking call: they stall the learning loop and create a backlog of unresolved debt.
• Follow-through rate: What percentage of action items from the last five postmortems are actually done? If it is below 50%, your postmortem process is a write-only memory. You are producing documents, not change.

These signals are not soft skills. They are measurable. You can track them in a spreadsheet. You can graph them over time. You can use them to predict which teams will still be functional in a year.

Uptime Is a Lagging Indicator with a Blind Spot

Uptime is easy to measure and easy to game. A team can hit 99.9% uptime by avoiding risky deployments, freezing features, and routing around broken services with manual workarounds. The system stays up, but the team’s capacity to change the system degrades. You are running a legacy system in production, and the legacy system is your own process.

Uptime also hides the cost of stability. If your team maintains uptime by having senior engineers manually restart flaky services at 3 a.m., your uptime metric is green while your on-call health is red. The postmortem for that 3 a.m. restart—if one is even written—will show the real cost: a human acting as a circuit breaker because the automated one was never built.

Postmortems capture the operational tax that uptime ignores. Every incident has a cost beyond the downtime: the engineer hours spent debugging, the context switches, the follow-up meetings, the documentation updates. A good postmortem process makes that tax visible. A bad one buries it.

The Race Condition in Your Incident Response

Most incident response processes have a race condition. The incident is happening in real time, but the postmortem is written afterward, often by the person who was on call. That person is tired, biased, and incentivized to make the incident look like a one-off. The result is a document that reads like a police report written by the suspect.

To fix this, separate the roles. The incident commander runs the response. A different person—someone who was not on the critical path—writes the postmortem. This is not about blame. It is about getting an accurate timeline. The person who diagnosed the failure has a mental model of what happened. The person who was watching from the outside has a different view. Both are useful. Neither is complete.

Another race condition: action items are assigned during the postmortem meeting, but the meeting happens days after the incident. By then, the urgency has faded. The action items become a list of good intentions. The fix is to assign action items during the incident, not after. When someone says “we should add a check for that,” write it down immediately. The incident is the highest-fidelity moment for capturing what went wrong.

Reading Postmortems Like a Senior Engineer

If you are a senior IC or EM, you should read postmortems the way you read code reviews: looking for patterns, not just bugs. Here is a practical method.

Step 1: Check the Timeline Density

A good postmortem has a timeline with timestamps, actions, and observations. A bad postmortem has a paragraph that says “the service was down for 45 minutes.” Timeline density is a proxy for observability. If your team cannot reconstruct what happened minute by minute, your monitoring is not good enough. You are flying blind, and the postmortem is the black box recording of the crash.

Look for gaps in the timeline. A 20-minute gap between “alert fired” and “engineer acknowledged” is a signal. It might mean the on-call rotation is understaffed, the alerting is too noisy, or the engineer was in a meeting. Each of those is a different system failure. The postmortem should name which one.

Step 2: Count the Blame Pronouns

Search the postmortem for the word “I” and the word “we.” A postmortem full of “I pushed the change” is a confession. A postmortem full of “we missed the edge case” is a cover-up. The healthiest postmortems use neither. They describe systems: “The deploy pipeline did not validate the configuration against the production schema.”

This is not about being nice. It is about accuracy. If the postmortem blames a person, the fix will be personal: “Bob will be more careful next time.” If the postmortem blames a system, the fix will be structural: “The deploy pipeline will reject configurations that fail schema validation.” One of these prevents recurrence. The other does not.

Step 3: Audit the Action Items

Action items are the only part of the postmortem that changes the future. Everything else is history. So audit them like a code review. Are they specific? Are they assigned to a person or a team? Do they have a due date? Are they tracked in the same system as your other engineering work, or do they live in a separate postmortem graveyard?

A common failure mode: action items are assigned to the person who caused the incident. That person is now responsible for both fixing the immediate bug and improving the system that allowed the bug. That is a double load. It is also a conflict of interest. The person who caused the incident is the least likely to advocate for a systemic fix, because a systemic fix implies the incident was not their fault. Assign action items to the people who own the system, not the people who broke it.

The Postmortem as a Cultural Artifact

Postmortems are not just technical documents. They are cultural artifacts. They record how your team handles failure, who gets to speak, and what gets remembered. In a healthy team, the postmortem is a place where junior engineers can ask “why did we do it that way?” without fear. In an unhealthy team, the postmortem is a place where senior engineers defend their decisions and junior engineers stay quiet.

Watch who writes the postmortems. If it is always the same person, you have a bottleneck. If it is always the most senior person, you have a hierarchy problem. If it is always the person who was on call, you have a process problem. The postmortem should rotate. Different perspectives catch different failure modes.

Watch who reads the postmortems. If postmortems are written and never discussed, they are write-only documents. The learning loop is broken. The fix is to schedule a postmortem review meeting, but not the kind where the author reads the document aloud. The meeting should be a discussion: what surprised us, what do we disagree with, what should we change about the process itself.

The Meeting That Kills the Postmortem

There is a specific meeting pattern that kills postmortem culture: the postmortem becomes a status update. The author walks through the timeline, everyone nods, and the meeting ends. No one challenges the timeline. No one asks why the detection took 30 minutes. No one questions whether the action items are actually going to prevent recurrence.

This is a blocking call in your team’s learning loop. The postmortem is produced, but it never blocks on anything. It just gets written to disk and forgotten. The fix is to make the postmortem review a working session, not a presentation. Put the document on a screen. Edit it live. Argue about the timeline. Delete vague action items. The postmortem should be a draft until the team agrees it is accurate.

Why This Matters More Than Your Uptime SLA

Your uptime SLA is a contract with your customers. Your postmortem process is a contract with your future self. The SLA says “we will be available 99.9% of the time.” The postmortem process says “we will learn from every failure.” One of these is a promise you can keep by doing nothing. The other is a promise you can only keep by doing the work.

Teams that optimize for uptime alone become risk-averse. They stop deploying on Fridays. They add more approval steps. They build a culture where the safest thing to do is nothing. Teams that optimize for postmortem quality become resilient. They deploy more often because they know they can recover. They take calculated risks because they know they will learn from the failures.

The metric you choose to optimize changes the system you build. If you optimize for uptime, you build a system that avoids failure. If you optimize for postmortem quality, you build a system that learns from failure. The second system is the one that survives contact with reality.

Practical Steps to Improve Your Postmortem Process

You do not need a new tool or a new framework. You need to change the way you write, review, and act on postmortems. Here are five concrete changes.

1. Write the Postmortem During the Incident

Do not wait until the incident is over. Open a document when the incident starts. Add timestamps as events happen. Capture the raw observations before they get smoothed over by memory. This is the difference between a black box recording and a witness statement. The black box is more reliable.

2. Separate the Timeline from the Analysis

The timeline is facts. The analysis is interpretation. Keep them separate. The timeline should be a list of timestamps and events. The analysis should be a separate section that explains why the events happened. Mixing them creates a document where the interpretation contaminates the facts. You end up with a timeline that says “the engineer made a mistake” instead of “the deploy failed at 14:32.”

3. Make Action Items Small and Specific

“Improve monitoring” is not an action item. It is a wish. “Add an alert for payment service latency above 500ms” is an action item. It is small, specific, and testable. If an action item cannot be done in a week, break it down. Large action items are a way of avoiding work. They sit in the backlog forever because no one knows where to start.

4. Track Postmortem Metrics

Measure your postmortem process like you measure your production system. Track time to postmortem, action item completion rate, and incident recurrence rate. If your time to postmortem is consistently over 48 hours, your process is broken. If your action item completion rate is under 50%, your process is a write-only memory. If the same incident recurs, your postmortems are not finding the real root cause.

5. Rotate the Postmortem Author

The person who writes the postmortem shapes the narrative. If the same person writes every postmortem, you get the same narrative every time. Rotate the author. Include junior engineers. Include people who were not on call. Different perspectives catch different failure modes. This is not about fairness. It is about coverage.

The Postmortem as a Hiring Signal

If you are interviewing for a senior IC or EM role, ask about the postmortem process. Not “do you have postmortems?” but “show me your last three postmortems.” The answer will tell you more about the team than any culture-fit question.

A team with detailed, blame-free postmortems and a high action item completion rate is a team that learns. A team with vague postmortems and a backlog of unresolved action items is a team that repeats. A team with no postmortems at all is a team that hides its failures. You do not want to join that team.

The same applies in reverse. If you are hiring, ask candidates to critique a postmortem from your own team. A senior engineer who can read a postmortem and identify the missing system fix is a senior engineer who will improve your process. A candidate who blames the engineer in the postmortem is a candidate who will blame your engineers when things go wrong.

FAQ: Incident Postmortems and Engineering Health

What is a good postmortem process?

A good postmortem process has three properties: it is timely, it is blame-free, and it produces specific action items that get done. Timely means the postmortem is written within 24-48 hours of the incident, while the details are still fresh. Blame-free means the document describes system failures, not personal failings. Specific action items means each item is small enough to complete in a week and assigned to a person or team with a due date.

How do I know if my team’s postmortems are actually working?

Track three metrics: time to postmortem, action item completion rate, and incident recurrence rate. If postmortems take more than 48 hours, the details are already fading. If fewer than half of action items are completed, the process is not changing anything. If the same incident recurs, the postmortems are not finding the real root cause. All three metrics should improve over time.

Why do postmortems often turn into blame sessions?

Blame sessions happen when the postmortem focuses on the person instead of the system. This is usually a sign of low psychological safety. Engineers are afraid that admitting a mistake will hurt their performance review, so they defend themselves instead of analyzing the failure. The fix is to change the language: describe what the system allowed to happen, not what the person did wrong. The system is the thing you can change.

Should every incident get a postmortem?

No. Not every incident deserves a full postmortem. A typo in a config file that is caught by a linter and fixed in five minutes does not need a formal write-up. But any incident that causes user-facing downtime, data loss, or more than 30 minutes of engineering time should get a postmortem. The threshold should be explicit, not left to the on-call engineer’s judgment.

What is the difference between a postmortem and a root cause analysis?

A root cause analysis is a method for finding the underlying cause of a failure. A postmortem is a document that records the timeline, the analysis, and the action items. A good postmortem includes a root cause analysis, but it also includes the operational context: who was on call, what alerts fired, how long the diagnosis took. The postmortem is the full record. The root cause analysis is one section of it.

The Next Step: From Postmortems to System Design

If your postmortem process is healthy, the next step is to use it as an input to system design. Every recurring incident is a design flaw. Every action item that keeps getting deferred is a missing abstraction. The postmortem is not just a record of what broke. It is a requirements document for what to build next.

This is the follow-up topic for this blog: how to turn postmortem action items into a system design backlog. We will look at how to cluster recurring incidents, identify the missing abstractions, and prioritize the work that prevents the next failure instead of just patching the last one. If your team’s postmortems are full of action items that never get done, that article will show you why—and what to do about it.

For now, start with the basics. Read your last three postmortems. Count the blame pronouns. Check the timeline density. Audit the action items. The results will tell you more about your team’s health than any uptime dashboard ever will.

There’s a particular species of tech lead that makes me want to file a ticket against the org chart. You know the one. They run standup, hand out work, sit in every planning meeting, have opinions about your variable names — and then, the moment you ask them to make an actual architecture call, they turn into a null pointer. This is the tech lead who is management without the title. All the accountability of leadership, none of the authority. All the meeting load of a manager, none of the budget. All the code review power of a senior engineer, none of the time to actually read the diff.

I call this the phantom manager pattern. It sits right next to the accidental manager, the lead by default, and the senior engineer who got promoted into a spreadsheet. It matters because it’s one of the most reliable ways to burn out your best people while telling yourself you’re developing leaders. The gap between what engineering teams say they value — autonomy, ownership, technical excellence — and what they actually do shows up in the operational signals. Deployment frequency drops. Code review latency spikes. Incident response turns into hot potato. Documentation freshness decays like an unmaintained cron job.

This is a systems problem, not a people problem. And like most systems problems, you can debug it if you stop blaming the individual and start looking at the feedback loops.

The Tech Lead Role Is a Race Condition

In most orgs, the tech lead role is defined by what it isn’t. It isn’t a manager, because managers do performance reviews and have direct reports. It isn’t a pure senior engineer, because seniors are supposed to write code and mentor. It isn’t an architect, because architects are supposed to draw boxes and disappear. So the tech lead becomes the catch-all thread that handles every blocking call the team generates.

This is a race condition. The tech lead is expected to:

• Run standup and sprint planning
• Review every pull request
• Write code for the hardest tickets
• Talk to product managers about scope
• Talk to other tech leads about cross-team dependencies
• Mentor junior engineers
• Debug production incidents
• Keep the documentation up to date
• Attend architecture review meetings
• Explain to the VP why the estimate was wrong

Every one of those is a blocking call. The tech lead is the only thread that can handle them. The result is predictable: the tech lead becomes a bottleneck, the team waits, and the work slows down. The operational signal is code review latency. If pull requests sit for days waiting on one person, you have a single-threaded bottleneck. The fix isn’t to tell the tech lead to work harder. The fix is to make the role non-blocking.

Management Without the Title Is a Legacy System

Here’s the uncomfortable truth: a tech lead who is management without the title is running a legacy system. The role was designed for a different era, when teams were smaller, codebases were simpler, and the distance between a decision and its consequence was short. Now the role gets patched with new responsibilities every quarter, like a monolith that keeps getting new endpoints bolted on. Nobody wants to refactor it, because that would mean admitting the org chart is wrong.

The symptoms are easy to spot if you look at the operational signals:

• Deployment frequency drops because the tech lead is the only one who can approve releases, and they’re in meetings all day.
• Incident response patterns become erratic because the tech lead is the de facto incident commander, but they’re also the only person who knows the database schema.
• Documentation freshness decays because the tech lead is supposed to keep it updated, but they’re too busy unblocking everyone else.
• Code review latency spikes because the tech lead is the only reviewer with enough context, and context is a finite resource.

These aren’t personal failures. They’re system outputs. The system is designed to route everything through one person, and then the system acts surprised when that person becomes a bottleneck. It’s like designing a load balancer with a single backend and then wondering why the site goes down on Black Friday.

The Authority Gap Is a Deadlock

The core problem with management without the title is the authority gap. The tech lead is expected to make decisions, but they can’t actually enforce them. They can suggest a coding standard, but they can’t put it in the performance review. They can recommend a refactor, but they can’t allocate budget for it. They can flag a toxic team dynamic, but they can’t fire anyone. They can push back on scope, but the product manager reports to someone else.

This is a deadlock. The tech lead is holding a lock on the team’s technical direction, but they’re waiting for a lock on authority that never gets released. The team sees the tech lead as a leader, but the org chart says they’re just a senior engineer with extra meetings. The result is decision paralysis. The tech lead stops making decisions because every decision gets overridden or ignored, and the team stops asking because they know the answer will be “I’ll check with the manager.”

The operational signal here is incident response patterns. When an incident happens, does the team know who’s in charge? Or does everyone wait for the tech lead to show up, and then the tech lead waits for the manager to approve the rollback? If your incident response looks like a game of telephone, you have an authority gap.

Why This Pattern Persists

You’d think a role this broken would get fixed. But the phantom manager pattern persists because it serves a purpose for the organization. It’s a cheap way to get management work done without paying for managers. The tech lead absorbs the coordination overhead, the meeting load, the cross-team communication, and the planning work — all without a title change, a pay bump, or a direct report. The org gets a manager for the price of a senior engineer.

This isn’t a bug. It’s a feature. The system is working exactly as designed. The problem is that the design is bad.

There’s also a cultural factor. Many engineers get promoted to tech lead because they’re good at writing code, not because they’re good at leading. The org assumes technical skill translates to leadership skill, which is like assuming a great quarterback will automatically be a great coach. The skills are related, but they aren’t the same. The result is a tech lead who’s excellent at debugging a race condition in the codebase and terrible at debugging a race condition in the team’s communication patterns.

What the Tech Lead Actually Needs

If you’re a tech lead stuck in this pattern, here’s what you actually need, in order of priority:

1. Decision authority. You need to be able to make a technical decision and have it stick. If you can’t do that, you’re not a lead. You’re a suggestion box.
2. Time to write code. If you’re not writing code, you’re losing context. And if you’re losing context, your code reviews are worthless. Block off at least one full day a week for deep work.
3. A manager who actually manages. You need someone above you who handles the people stuff — performance reviews, career conversations, conflict resolution — so you can focus on the technical stuff. If your manager is also a phantom manager, you’re both doomed.
4. A clear scope. You need to know what you’re responsible for and what you’re not. If the answer is “everything,” that’s not a scope. That’s a trap.
5. A path to a real title. If you’re doing management work, you should get the management title and the management pay. If the org won’t give you that, start looking for an org that will.

How to Debug the Phantom Manager Pattern

If you’re a manager or a director reading this and you recognize the pattern in your own org, here’s how to debug it. Treat it like a production incident, because that’s what it is.

Step 1: Measure the Bottleneck

Look at your operational signals. What’s the code review latency? How many pull requests are waiting on one person? How many meetings does your tech lead attend per week? How many decisions get escalated to them? If the answer to any of these is “too many,” you have a bottleneck.

Step 2: Identify the Missing Locks

What authority does the tech lead actually have? Can they approve a refactor? Can they change the sprint scope? Can they tell a senior engineer to stop bikeshedding? If the answer is no, you have an authority gap. Fix it by giving them the authority, or by taking the responsibility away.

Step 3: Refactor the Role

Split the role. If the tech lead is doing management work, make them a manager. If they’re doing architecture work, make them an architect. If they’re doing both, you have two roles crammed into one person, and that person is going to quit. The refactor is painful, but it’s less painful than losing your best engineer.

Step 4: Watch the Signals

After you refactor, watch the operational signals. Did deployment frequency go up? Did code review latency go down? Did incident response get faster? If yes, you fixed the system. If no, you moved the bottleneck somewhere else. Find it and fix it again.

The Cost of Ignoring the Pattern

If you ignore the phantom manager pattern, here’s what happens. Your tech lead burns out. They start looking for a new job. They find one. They leave. You lose the person who knew the most about the codebase, the team, and the architecture. The team loses its de facto leader. The codebase loses its institutional memory. Deployment frequency drops further. Code review latency spikes further. Incident response gets worse. And then you promote the next senior engineer into the same broken role, and the cycle repeats.

This is the tech lead churn loop. It’s one of the most expensive patterns in software engineering, and it’s entirely preventable. The fix isn’t to hire better tech leads. The fix is to design a better role.

What a Healthy Tech Lead Role Looks Like

A healthy tech lead role has three properties:

1. Bounded scope. The tech lead owns a specific area — a service, a module, a team — and they’re the final decision-maker for that area. They’re not responsible for everything. They’re responsible for one thing, and they do it well.
2. Real authority. The tech lead can make decisions that stick. They can say no to scope. They can enforce coding standards. They can allocate technical resources. They don’t need to ask permission for every small thing.
3. Protected time. The tech lead has at least one full day a week with no meetings, no interruptions, and no firefighting. They use that time to write code, review pull requests, and think about the architecture. If they don’t have that time, they’re not a tech lead. They’re a meeting attendee with a fancy title.

If your tech lead role doesn’t have these three properties, you don’t have a tech lead. You have a phantom manager. And phantom managers don’t scale.

FAQ

What is the difference between a tech lead and a manager?

A tech lead is responsible for technical decisions — architecture, code quality, technical direction. A manager is responsible for people decisions — hiring, firing, performance reviews, career growth. The problem is when a tech lead is expected to do both without the title or authority of a manager. That’s the phantom manager pattern.

How do I know if I am a phantom manager?

Ask yourself three questions: Can I make a technical decision and have it stick? Do I have at least one full day a week to write code? Do I have a manager who handles the people stuff? If the answer to any of these is no, you’re probably a phantom manager. The operational signals are also telling: if code review latency is high, if deployment frequency is dropping, if incident response is chaotic, you’re likely the bottleneck.

What should I do if I am a tech lead stuck in this pattern?

First, document the problem. Write down what you’re responsible for, what authority you actually have, and where the gaps are. Then take that document to your manager and ask for a specific change: either give you the authority, reduce the responsibility, or change the title. If your manager won’t make a change, start looking for a new role. Life is too short to be a bottleneck.

How can a manager fix the phantom manager pattern on their team?

Measure the bottleneck first. Look at code review latency, meeting load, and decision escalation. Then identify the missing authority. Then refactor the role — split it into a technical track and a management track if necessary. Then watch the operational signals to see if the fix worked. The key is to treat it as a systems problem, not a people problem.

Next Steps for This Blog

This article is part of a series on operational signals that reveal broken team dynamics. The next piece will look at code review latency as a cultural diagnostic — what your pull request queue says about your team’s trust, autonomy, and decision-making patterns. If you have a war story about a phantom manager, a tech lead churn loop, or a role refactor that actually worked, send it over. I read everything, and I’ll quote the good ones.