Bluefield: extracting a spec from a running legacy system

Bluefield: reverse-deriving a spec from a system that's already running

Every team has one. The file nobody opens without a reason and a backup plan. Its behavior holds production up, whoever wrote it left the company two jobs ago, and the only description of what it does that you'd actually bet on is the source itself. Bluefield is the SDD move that turns that file from a liability you route around into an artifact you own — and the artifact, not the rewrite it might unlock, is the whole point.

The load-bearing mystery

You know the file. Six hundred lines, a name like `billingReconcile.js`, last meaningful commit three years back by someone who's since left. The Confluence page is confidently wrong: it documents the 2019 intent and none of the four hotfixes that came after. The senior dev everyone forwards questions to carries a mental model of the happy path plus the two or three edge cases that once burned them. The other forty edge cases live in the code and nowhere else, and you meet them at runtime, usually around 2am.

Say the uncomfortable part out loud: nobody in the building actually knows what that system does. The knowledge exists, but it's smeared across the source, a handful of war stories, and a production database full of rows that only parse if you already know the undocumented rule. This isn't a documentation problem. The knowledge was never externalized in the first place, and the code is the last place it's still true.

The third scenario

You know the first two already. Greenfield: SDD writes a spec, then generates a new system from nothing. Brownfield: SDD guides changes into a system that already exists, checking each edit against what's there. Bluefield is the third, and it runs the arrow backwards.

• ▹Greenfield — spec first, code second. You own the intent; the running system doesn't exist yet.
• ▹Brownfield — code first, spec as you go. You change a living system incrementally, spec-checking each edit.
• ▹Bluefield — code first, spec extracted. Point SDD at a running legacy system and reverse-derive an executable spec of what it provably does today, edge cases and all.

The name is deliberate. Green is new grass. Brown is the dirt you're already standing in. Bluefield is water you can only see the bottom of once you stop stirring it — the system was always running, always opaque; the pass is what makes it legible.

The counterintuitive move: the first deliverable is not code

Say 'bluefield' and everyone pictures a rewrite. That instinct is exactly why most legacy modernization dies in a planning meeting. The first deliverable of a bluefield pass isn't code. It's a spec: a precise, testable description of what the current system does across every input the code actually handles. Not what it should do. Not what the ticket promised in 2019. What it provably does today.

This is the shape of work an LLM is unreasonably good at now and was useless at three years ago. Reading 40k lines of undocumented code to answer 'what happens when this field is null and that flag is set' is tedious, mechanical, high-context reading — the exact thing that breaks human attention and sits dead center in an agent's wheelhouse. Point an agent at the source, or a fleet of them, one per module, and it drafts behavioral clauses: inputs, branches, side effects, error paths. You don't trust that draft yet. You make it earn trust with tests, further down. But it already captures things no Confluence page and no senior dev's memory ever held, for the simple reason that no human ever sat and read all of it at once.

## Extracted behavior: billingReconcile

- WHEN invoice.status == 'partial' AND payment.currency != account.currency
  THEN convert at payment.date FX rate, NOT invoice.date  # undocumented; found in code
- WHEN customer.tier == 'legacy_2018' THEN skip late-fee accrual  # nobody remembered this
- WHEN reconciliation runs twice in same UTC day THEN second run is a no-op (idempotency guard)
- EDGE: negative line-items allowed only if a matching credit-note exists within 90 days
- EDGE: rounding uses banker's rounding, not half-up  # source of a 3-year-old support ticket pattern

Why the spec is the asset, not the rebuild

Here's the reframe that flips the ROI math. A rewrite starts depreciating the day you ship it: new stack, fresh tech debt, a new mystery for whoever inherits it. The spec does the opposite. It appreciates. It outlives the person who wrote it, the framework you happened to pick, and the language the system runs in. The next engineer inherits a described system instead of a haunted one.

And the value lands before you regenerate a single line. The day the spec exists and is verified, you've already turned a person-shaped dependency into an org-owned artifact. Skip the rewrite entirely and you've still won. That's the sentence that gets budget: not 'the rewrite will be cleaner' — unprovable, everyone's heard it, everyone's been burned — but 'we will own a tested description of a system we currently only pray about.'

Make it a method, not a slogan

'Extract a spec' is a vibe until it has steps and a rollback at each one. Here's the loop that makes bluefield safe enough to put your name on:

• ▹1. Extract the spec — agent reads the running system, drafts behavioral clauses with edge cases. Human reviews for plausibility, not completeness yet.
• ▹2. Build a golden test suite from the spec — the critical inversion: both the OLD system and any NEW system must answer to the same tests. If old prod fails a test, your spec is wrong, not prod. Fix the spec. This is how the spec earns trust.
• ▹3. Regenerate ONE slice — not the whole thing. Pick the smallest coherent behavior. Generate a replacement from the spec.
• ▹4. Diff behavior against production — run the golden suite plus shadow/replay real production traffic against the new slice. Compare outputs, not code.
• ▹5. Cut over that slice — behind a flag, reversible. Old path still there. If the diff is clean under real load, flip. If not, flip back and fix the spec or the slice.
• ▹6. Repeat slice by slice — the system is never in a big-bang state. Every step is independently shippable and independently revertible.

The golden suite is the load-bearing idea here — a contract both systems have to sign. In an AI-first setup it's cheap in a way it never used to be: agents draft the cases from the spec, generate the replacement slice, and you can afford to shadow real production traffic through both paths for days, because an extra comparison run costs inference, not an engineer's week.

Why leadership can sign this version

The classic rewrite pitch is 'trust me, it'll work,' a big-bang cutover, and a prayer. No competent exec signs that, and they're right not to. Bluefield hands them three things they can actually evaluate: a staged plan instead of a cliff, a rollback at every step — the old path stays until the new one is proven under real traffic — and an insurance framing, because you're recovering knowledge the org is bleeding out every time someone resigns.

That framing beats the technical one. 'We are one resignation away from nobody understanding how we bill customers' is a risk a CFO gets in one sentence. The spec — bluefield's first deliverable — retires that risk directly, and it retires it before the expensive part even starts. You're not selling a rewrite. You're selling a de-risking that happens to make a rewrite possible.

The real friction is human, not technical

Here's the part the tooling threads skip. Extracting the spec is the easy 80%. The hard 20% is politics. The moment the black box cracks open, the 'only Minh understands the billing engine' bottleneck dissolves. Downstream that's pure relief — Minh stops getting paged on vacation, the team stops waiting on one person, onboarding drops from months to days. But to whoever held the keys, you just externalized the thing that made them irreplaceable.

Be honest that this is a real cost to a real person, and design for it instead of pretending it isn't there. The move that works: make the key-holder the owner of the extraction, not its casualty. They become the person who authored the org's spec, reviewed the agent's draft, caught what the agent missed — a promotion in scope, not a demotion in relevance. Get that framing wrong and your most knowledgeable engineer quietly slow-walks the whole thing, and they'd be right to, because you just turned their expertise into a layoff risk. The technical plan can be flawless and still die right here.

Where this leaves you

After a bluefield pass you're holding something you didn't have yesterday: a spec of what is. Behavior stopped being a mystery you steer around and became an artifact you own, version, and test against. That's the Day 3 payload — not the rebuild, the ownership. The next move is the interesting one: what changes once behavior is something you hold in your hand instead of something you fear. When 'what the system does' is an artifact, you can diff it against 'what it should do,' generate against it, and evolve it on purpose — which is exactly where the next lesson picks up.

Extend your knowledge

• ▹Michael Feathers, 'Working Effectively with Legacy Code' — the characterization-test idea is the pre-AI ancestor of the golden suite; read it, then notice how much cheaper agents make it.
• ▹Pick your own scariest file this week. Point an agent at it and ask only for a behavioral spec with edge cases — no rewrite. Review the draft with whoever knows it best and count how many clauses surprised even them.
• ▹Read up on shadow deployment / traffic replay (dark launching) — the diff-against-production step depends on it; look at how teams route mirrored real traffic to a candidate service.
• ▹Study GitHub's Spec Kit and the broader SDD tooling conversation to see how 'spec as an executable artifact' is being formalized, then map its greenfield examples onto the bluefield direction.