Brownfield is the opposite of a blank slate: the code already exists, real users may depend on it, and the people who built it may be long gone. The danger here isn't a lack of information — it's conflicting information. You'll find documentation, you'll find old tickets, you'll find the running code, and you'll find a business with opinions about what it wants now. Each claims to describe the system, and they don't agree. Charging in to change code before you've sorted out which of them to believe is how brownfield work goes sideways.
Four sources of truth that disagree
Picture four witnesses to the same system, each reliable in a different way. Docs and specs describe what was intended — but they go stale the moment code changes without them. User stories capture the originally agreed intent, the contract that was signed off. The implementation — the code itself — is the strongest evidence of what the system actually does today, though it may contain bugs nobody noticed. And business intent today is the live tiebreaker: what the organization wants now, which may have drifted from anything written down. None of the four is automatically right. The job is to cross-examine them.
Rule #1: verify a source of truth before touching anything
The first move is not to write code — it's to establish a trustworthy source of truth. You verify the docs against the code: where they agree, you trust them; where they diverge, the code wins as evidence of current behavior (while you note the divergence as a gap, not a fact). If there are no usable docs at all, you reverse-engineer a spec straight from the implementation, marking what you inferred and listing what the code alone couldn't tell you. Either way you end up with an accurate description of what the system does today, which is not yet the same as what it should do. So you import the existing user stories too, putting the original agreed intent on the table. Only once you have a verified picture are you allowed to think about change.
How it works: reconcile into a gap map
With all four sources assembled, you run a four-way reconciliation: line up docs, stories, code, and today's business intent, and write down every place they disagree. The output is a gap map — a plain table where each row is one disagreement, with what each source says, a provisional classification, and a specific question for the business. The business is the tiebreaker on intent, so their answers settle the rows you can't settle from the evidence alone. The gap map is the deliverable of this whole phase; nothing gets built until every row has a verdict.
Corrections vs. new requirements
Every gap falls into one of two buckets, and confusing them is the classic brownfield mistake. Corrections are places where reality and the agreed intent have drifted apart by accident: a stale doc that needs fixing to match the code, or a genuine bug where the code does something the stories never agreed to. The tech team owns corrections — they're cleanup, not new scope. New requirements are different in kind: the business has changed its mind, so a gap exists because today's intent no longer matches what was built. That isn't a bug to quietly patch — it's new scope. The business owns these. You flag them, route them for approval, and never silently absorb them into the spec, because doing so smuggles unreviewed scope into the build.
Step through a small gap map for an inherited refund feature. In each row, notice which source is the odd one out: odd docs mean a stale doc, odd code means a bug, and an odd business column means a new requirement. You'll classify one row yourself before the answer appears. At the end, replay the last row with a developer who quietly absorbs the new requirement, and watch what happens to the evidence.
Reconciling an invoicing feature, you find the docs say invoices are emailed as PDFs. The stories, the code and the business all say customers get a link to the billing page instead. What is this gap?
The code is evidence, not the truth. When docs and code disagree, it's tempting to declare the code correct and rewrite everything else to match. That's right for a stale doc. But if the stories and the business both say otherwise, you've just written a bug into the spec and made it official. The code tells you what the system does today; only the stories and the business can tell you whether that's what it should do.
In our stack — we lean on Claude Code (the harness, on one of Anthropic's Claude models) to do the heavy reading that humans skip: it can reverse-engineer a spec from the code, diff that against the imported docs and stories, and draft the gap map for us. But the classification gate is human: Claude Code flags each row as a likely correction or likely new requirement, and we confirm — especially that nothing tagged 'business changed its mind' is silently folded into the spec. Claude Code reconciles; people approve scope.
Lock the spec, then rejoin greenfield
Once the corrections are applied and the new requirements have been routed for their own approval, you lock the spec — freeze the now-trustworthy source of truth — and from there the work rejoins the ordinary greenfield workflow: the locked spec runs down the functional and technical tracks, through the same review gates, to build-ready. A new requirement the business approves doesn't get patched into the locked spec either. It enters the greenfield flow from the top as a new feature, with its own spec, stories and approval. Brownfield, in other words, is just greenfield with an investigation bolted onto the front: you earn a clean spec first, and only then build against it.
During reconciliation the business says, "While you're in there, also let customers pay with gift cards." No doc, story or code mentions gift cards. What do you do?