The Brownfield Workflow

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.

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.

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. Then you import the existing user stories so the original agreed intent is on the table too. Only once you have a verified picture are you allowed to think about change.

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, classified by type. The gap map is the deliverable of this whole phase; nothing gets built until every row has a verdict. The diagram below shows the four sources feeding a reconciliation node, which produces the gap map, which then splits into two very different piles.

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.

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. 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.