skip to content
$cat reviewing-for-coherence.md

Correct Code, Wrong Change: Reviewing for Coherence

19 min readby MDflowview as .md
An emerald wireframe assembly of flat panels locking into one smooth curved surface, with a single newly inserted panel raised and rotated out of alignment, above a receding row of dimmed older panel outlines on a dark terminal grid

A product accumulates a settings page nobody designed. Each toggle on it was a correct change: it compiled, it passed review, it shipped. Add forty of them over two years and you have something no reviewer would have approved as a whole, assembled entirely out of changes every reviewer approved one at a time.

That failure has always existed. What is new is the rate — and it is why reviewing for coherence is now a separate job from reviewing for correctness. Tom Moor, head of engineering at Linear and the founder of Outline, argued in an AI Engineer talk published on 9 November 2026 that implementation has stopped being the bottleneck, and that the thing which breaks next is not our ability to build but our ability to keep a product coherent while it is built faster than anyone can read it.

TL;DR — Code review agents are good at correctness and blind to coherence, because the information that decides whether a change belongs in the product — the intent, the trade-off made last year, the design already rejected, the revert two weeks ago — is nowhere in the diff. The fix is not a better reviewer; it is carrying that context through intake, implementation and review, and writing the judgment down where the next agent can read it. Plain markdown in a workspace like MDflow is one place to put it. Start free.

What reviewing for coherence means, and why a diff cannot carry it

Coherence is the property that makes a product feel like one thing rather than forty correct things. Moor's description of what makes a product good is consistency, restraint, trade-offs, and a large number of small decisions that reinforce one another. Every item on that list is a relationship between changes. None of them is visible inside a single change.

Correctness is different in kind: it is derivable. An agent reading your repository can work out types, call sites, test expectations, naming conventions and the shape of your error handling, because all of it is present in the text. Coherence is not derivable from the same text, because the deciding facts were never written into it.

Linear's own engineering write-up on reviewing code in the agent era, published 10 June 2026 by Maciek Pekala, reaches the same split from the other direction. He reports that between January and March the team's issues created and pull requests merged both climbed by 50%, and says he no longer reads line by line, because agents now mostly cover finding bugs and checking logic correctness. The time that frees up goes to a different question, and his summary of it is the clearest one-line statement of the problem this post is about — for Linear, quality review has come to mean that the code is "useful, not just correct".

The failure mode he names is precise: every so often the change is solving the wrong problem, because someone — or an agent — took the brief too literally.

The six things your coding agent cannot see

Moor's list of what a coding agent misses when it reads only the code:

  • The intent. What problem is this solving, and why does it matter to the person using the product?
  • The decisions already made. Which trade-offs produced the current design, and what was given up to get it?
  • How it should look and feel. The part of a product specified in judgment rather than in code.
  • What else is in flight. Work underway in another team that this change will collide with.
  • Who decides. The person who owns the trade-off, who is often not in the codebase at all — a product lead, a designer, a founder.
  • The risk signals. A revert in this area two weeks ago. A regression. An incident. Visible in history if you know to look, invisible in a diff.

Two of those are history, two are organisational, one is taste, and the first is the brief itself. A reviewer that reads only the repository gets none of them.

Three cases where the extra context was the whole review

Moor showed three reviews from the weeks before the talk. He hedged the system itself — most of it in production "in some form" — so take these as his reported examples rather than a benchmark.

1. The incident nobody could see in the diff. A review agent working with product history surfaced related changes from six and seven months earlier and flagged the pull request as an incident risk, because it held a database transaction open. Moor's note on this one is the interesting part: he said a conventional review agent may have been able to find it, and that Codex did not.

2. The design that had already been rejected. A pull request re-added iconography that had been dropped roughly a year earlier for making the interface too busy — a decision that, he said, had been made more than once. This is the purest case. There is nothing wrong with the code. The only reason not to merge it is a judgment someone made a year ago, and the review agent surfaced it because that judgment had been written down.

3. The invariant defined in no single place. Workspace labels were rendering below team labels, inverting a hierarchy the product maintains. As Moor put it, there is no place in the code that defines that ordering, because labels are listed in many places. What caught it was a previous revert and a related issue — again, history recorded outside the code.

The thing to take from cases 2 and 3 is not that the reasons were lost. It is the opposite, and it is the whole argument of this post: the reasons existed in a durable, machine-readable form, and that is the only reason they were catchable. Neither is recoverable from the repository at any cost. Both were recoverable from the record. A team that never writes the record down has no version of this review available to it, no matter which model is reading the diff.

Carrying the context instead of reconstructing it

Moor's framing is that context is moving out of the agent's inner loop and into the stages around it. A terminology note, since we have used the phrase differently: in The Agentic Coding Loop we called the outer loop the human's steering cycle. Moor is describing those same outer stages becoming automated — which is the point. If agents run for hours and cost cents, nobody is hand-feeding them context at each boundary.

Intake. Ideas arrive from support tickets, Slack, sales calls, alerting, the CEO. Moor's team routes them into triage, where an agent labels, assigns, groups them into themes, closes duplicates and asks for clarification when the problem is underspecified. It also investigates, and leaves the investigation on the issue as context for whoever — or whatever — picks it up: who asked, how valuable the customer is, how many times they have asked before, stack traces, logs, related past work and the decisions made on it. His example: a bug where captions kept switching on, where the triage agent reproduced it and found an automatic browser action being mistaken for user intent. That diagnosis, sitting on the issue, is what made the automatic fix work.

Worth dating the product claim rather than guessing at it: Linear's write-up on Triage Intelligence describes flagging duplicates, linking related issues and recommending properties like labels and assignees, each with a brief explanation — and, as of that post in September 2025, calls it a technology preview on Business and Enterprise plans. Moor was speaking more than a year later, Linear has shipped further agent capabilities since, and he said most of what he showed is in production "in some form" and usable by others. Check Linear's current documentation rather than the 2025 snapshot if you are evaluating the feature; the principle below does not depend on it.

Implementation. Moor called this close to solved and spent almost no time on it. What matters, in his account, is the base context from intake, plus the ability to verify, plus continuous-integration failures feeding back to the agent. That matches the argument in The AI Code Verification Loop, which splits verification into the genuinely hard part — multi-layered, zero-trust checking — and the merely neglected part: writing down, before the agent starts, the rules it is about to break.

Review. This is where he thinks the thinking is still missing, and where most teams' setup is a review agent reading the diff and the repository. Linear's review agent starts from the original issue and the intake context, then adds product history — previous decisions, reverts, regressions, incidents in the same area — the diff and its intent, refreshed related issues, overlapping or conflicting changes in flight, the full agent session that produced the code, and ownership, which tells you who should make the product call and where review coverage is missing. This slots into the middle layer of the split we described in AI Pull Request Review: scripts prove, an agent judges, people own the protected calls. Coherence lives entirely in the judging layer, and it is the layer most starved of input.

Distillation. The last stage is the one most teams skip. A daily automation trawls the code merged that day, extracts actionable lessons from the comments and reverts, and writes them back into the agents file or the related documentation, so that human judgment spent once becomes context the next loop reads. Moor's caveats are worth keeping: the prompt is trial and error, you do not want the file to grow without bound, and any automation tool will do it.

But prose was supposed to be the thinnest layer

We argued in Lint Rules Beat Rules Files that prose instructions are unenforceable and that agents treat a markdown rules file as a ledger of excuses. An automation that writes lessons into an agents file every day is, on its face, a machine for manufacturing exactly that.

But that post already supplies the filter, and its own closing test is the right one to run here: can this correction be made deterministic? If the agent copied a bad pattern, delete the pattern. If it crossed a boundary, make the boundary a directory and fail the build. A lesson a check could express belongs in the check, where it fails the build identically for every agent and every human and the error message does the teaching. Only when none of that is possible should the correction become prose — and then, in that post's words, somewhere canonical, dated and reviewable rather than appended to a file nobody re-reads.

What survives that filter is the residue no check can hold: a decision made, an option ruled out and why, an invariant that spans eleven files and is defined in none of them. Case 2 and case 3 above are both in that residue.

So the distillation loop is right about where the judgment should go and dangerous about what it writes. Point it at records, not rules. A dated note saying "we considered compact icons here in 2025 and dropped them for visual noise" cannot go stale, because it never claimed to be current — the same distinction we drew in Agent Archaeology, which is this problem seen at the handoff rather than at the review gate. A line saying "always prefer compact icons" is a rule with nothing enforcing it, and that one rots.

This is also, mechanically, memory consolidation applied to a team instead of to a single agent's scratchpad: a scheduled pass that merges, prunes and promotes what the fast path wrote.

Which teams benefit most

  1. Teams where agents merge faster than anyone reads. Linear's own reported 50% rise in merged pull requests in one quarter is the shape of this.
  2. Products with a deliberate design language. When consistency is the value, an incoherent correct change is a defect.
  3. Long-lived products. The rejected design was usually rejected before the current team arrived.
  4. Teams running several agents from several vendors. The record has to live outside all of them, which is the model-agnostic argument applied to review context.
  5. Regulated or audited work. "This alternative was evaluated and rejected because…" is rarely recoverable after the fact.
  6. Anything with cross-surface invariants. Ordering, hierarchy, naming and precedence rules that hold across many call sites and are written down in none of them.

How MDflow fits

The boundary first, because this topic runs through somebody else's product. MDflow is not an issue tracker and not a review tool. It does not see your pull requests, read your continuous-integration output, or know a revert happened. The integrated pipeline Moor described is Linear's, and if that is what you want, that is where to look.

What MDflow is, for this problem, is the durable and portable half: the place the distilled judgment lands, in a format any agent can fetch during a review.

What lines up today

  • Retrieval by purpose, not by filename. A folder description is MDflow's primary ranking signal, and mdflow_get_context ranks those descriptions above folder names and document titles. A folder described as "product decisions and rejected designs for labels, filters and the sidebar" is what an agent finds when it asks about a label change — the mechanism we cover in Folder Descriptions as Agent Context.
  • Read and write, both directions. The MCP server and the versioned HTTP API both write, so the agent that did the work can file the record itself, and the review agent can read it on the next pass. See Let AI Agents Write to Your Knowledge Base.
  • One copy, many clients. The same workspace serves Claude Code, Claude Desktop, Cursor, Codex, ChatGPT and any script holding a token. Claude connects in one click through the MDflow connector.

Connect Claude to MDflow: open the MDflow connector in Claude's Connectors Directory, click Connect to Claude, and sign in — no URL or token to paste. One connection covers claude.ai, the Claude desktop and mobile apps, and Claude Code signed in with a Claude subscription. Team workspaces use a mdt_ Team access token instead, with the bearer-header client configurations listed in the MCP docs.

  • A shared workspace with real permissions. Teams gives a Team account its own workspaces with per-member access set to no access, read-only, or read/write/delete. Team access tokens (mdt_…) are bound to one Team account and to named workspaces, capped read-only or read-and-write, and re-checked against live membership on every request — so a colleague's review agent reads the same record under their own permissions.
  • Version history that covers machine writes. Every saved body change keeps the previous version across every write path, including the API and the MCP server, with a line-by-line diff and a non-destructive restore (Pro; 30 days or the last 300 versions). A Team seat carries it for every active member.
  • An answer to "what did the agents change?" In a personal workspace, the Document Log at /log records created, edited, shared and deleted events with the actor on every row — you for browser actions, automated · <token name> for anything arriving over the API or MCP — and an edited row opens a diff of what changed, retained 30 days. Team accounts keep a separate audit feed of lifecycle changes, retained 365 days.
  • A scheduled distillation pass is buildable, not built in. The n8n-nodes-mdflow community node puts 22 operations plus a polling trigger for new content on the canvas, so a nightly workflow can read a source, transform it, and write the day's decisions into a folder. See the n8n guide.

Where the report card is worse. Five gaps, all real:

  • No provenance link. Nothing connects a document to the pull request, commit or issue that produced it. You can paste a URL; nothing maintains it, and nothing notices when the code moves on.
  • Version history is not reachable by an agent. Active Team members can compare and restore versions of a Team document in the editor, but history is not exposed over the API or MCP, so no agent can ask what changed in the record and when. On personal documents it is narrower still: private to the document owner, and Pro-only.
  • Team documents have no comments. Commenting works on personal documents shared by public link or by email; inside a Team workspace it is deliberately absent until it gets a Team-specific persistence and authorization design. The argument about a trade-off therefore happens somewhere else, and only its conclusion arrives here.
  • Personal access tokens are not scoped. An mdf_ token is account-wide, read and write, with no read-only option and no per-workspace restriction. Only Team tokens are scoped, so size the blast radius of a token you hand to a review job deliberately.
  • Writing the record is still a step. Nothing in MDflow notices that a decision was made. This is the step that gets skipped, in this tool and every other one, and it is the honest reason most of this context does not exist anywhere.

Where we are headed — direction, not a dated commitment. The folder description stays the primitive we invest in, because stating what a set of documents is for is what makes retrieval work without an index. Beyond that: narrower read-only credentials for agents that should only ever consume context, document history reachable by the tools that write the documents, and shrinking the distance between where a decision gets made and where it gets written down.

The bottom line

Review agents are now good at the question the code can answer. The question the code cannot answer — does this change belong in the product — is the one that decides whether forty correct merges add up to a product or to a settings page.

That question needs inputs: the intent, the decision already made, the design already rejected, the thing that broke here last month, the person who owns the call. None of it is in the diff, and no amount of reasoning recovers it. It has to be written down, in dated records rather than standing rules, somewhere every agent on the team can read with its own credentials.

Moor's closing line on stage is the right summary of why this is worth the step: our judgment matters more as code gets cheaper.

Start free, connect an AI agent, or read the API docs.

Frequently asked questions

Why does an AI coding agent write code that is correct but still the wrong change?

Because correctness is derivable from the code and coherence is not. An agent reading a repository can infer types, call sites, test expectations and house style. It cannot infer what problem the change was meant to solve, which alternative was considered and rejected last year, what was reverted in that area two weeks ago, or who owns the trade-off. None of that is written in the code, so a change can satisfy every check in the repository and still not belong in the product.

What context can a code review agent not get from the codebase?

Six things, in the list Tom Moor of Linear gave in his AI Engineer talk published on 9 November 2026: the intent behind the change and why it matters to a user; which decisions were already made and what trade-offs produced them; how the result should look and feel in the product; whether related work is underway somewhere else in the organisation; who the decision maker is; and risk signals such as a revert, regression or incident in the same area. A reviewer who only reads the diff is missing all six.

Is reviewing for coherence different from reviewing for correctness?

Yes, and they need different inputs. Correctness review asks whether the code does what it says, and it is increasingly well covered by deterministic checks and review agents reading the diff. Coherence review asks whether this is the right change for the product — whether it duplicates an existing concept, contradicts a decision already made, or conflicts with work in flight. Linear's own write-up on reviewing code in the agent era puts the distinction as quality meaning the code is useful, not just correct.

Should an automation write lessons from merged pull requests into your agents file?

Only the lessons that cannot be expressed as a check. A lesson that a linter, type or test could enforce belongs in that check, where it fails the build identically for every agent and every human. What is left over is the judgment layer — a decision made, an option ruled out, a convention that spans several files and is defined in none of them. Moor's own caveat on stage was that you do not want the file to grow without bound, and an agents file full of unenforced prose is the failure mode to avoid.

Where should a team keep the product decisions its review agent needs to read?

Somewhere every agent on the team can reach with its own credentials, outside any one vendor's issue tracker or any one person's machine. Plain markdown in a shared workspace works because the text a human reviews is the text an agent retrieves, and it can be fetched over an API or an MCP server during a review. The test is whether a review agent running on someone else's laptop, under their own token, can find the reason a design was rejected a year ago.

Further reading