§4.3 Brownfield Engineering
The DocAble episode began with an engineering problem and developed models as the work exposed new questions. Brownfield engineering often begins from the opposite direction: the system already exists, and consequential knowledge is distributed across code, tests, documents, and operational practice. How can engineers recover the models and obligations needed to govern subsequent changes?
4.3.1 Start from the System You Own
Most readers do not begin on a blank page. You inherit code, tests, schemas, architectural documents, CI rules, permissions, dashboards, conventions, and operational lore. Some of that inheritance is debt; some is useful engineering structure that has become fragmented, stale, or difficult to reuse. Brownfield engineering is therefore partly an exercise in recovery: find the representations and controls the system already owns, reconnect them to the territory they describe, repair or retire what has drifted, and invest in new structure where recurring engineering costs justify it.
The objective is not to model the entire existing system before agents can work on it. It is to make the next consequential change safely, then improve the engineering environment so that later changes become easier to govern. Existing tests, permissions, architecture documents, and review practices are starting points. Some already enforce useful obligations; others depend on someone remembering what to check. The work is to discover which is which, establish what can be trusted, and strengthen the environment one important property at a time.
SOFTWARE ENGINEERINGInset — Software evolves; its engineering structure must evolve with it
The inherited structure can become stale because the software itself keeps changing. Lehman's work on software evolution observed that systems embedded in a changing real-world environment must continually adapt, while their complexity tends to increase unless engineers act to control it 1.1. Meir M. Lehman and L. A. Belady, Program Evolution: Processes of Software Change (Academic Press, 1985).
Models and governance mechanisms need corresponding maintenance. For example, retiring a service may leave its old dependencies in an architecture model and its recovery steps in a runbook. Both artifacts still exist, but neither describes the current system. A brownfield inventory therefore needs to establish which models, checks, and procedures remain applicable, which need repair, and which can be retired.
A fast-built system may need to author models that implementation never made explicit. An established organization may instead need to reconcile fragmented ADRs, schemas, tests, ownership records, and operating procedures. Both start by inventorying what remains useful; neither requires a complete governed environment before work begins. The age of the implementation also does not settle its intent: a new regulated system can have firm obligations, while a mature product may still be exploring what users need.
Recovery becomes worthwhile when engineers or agents repeatedly reconstruct the same concept, cross the same hidden boundary, or search the same unproductive region. An explicit representation can then cost less than continued rediscovery. The implementation often already contains the evidence, expressed repeatedly without a shared name.
4.3.2 Recover Latent Models
Begin with two questions. What does the organization already reason through? Which documents, schemas, graphs, tests, or configurations repeatedly save engineers from reconstructing the system from raw implementation? These are candidates for recovered models.
What is already enforced? Which permissions, types, CI checks, reviews, and operational gates govern work, and which obligations do they help enforce? A mature system may already contain substantial local Alignment even when its system-level representations are weak.
Several techniques can help recover models from an existing system:
- Static program analysis. Analyze source code, types, dependencies, and configurations to recover structural relationships without executing the system 2.2. Stéphane Ducasse and Damien Pollet, “Software Architecture Reconstruction: A Process-Oriented Taxonomy,” IEEE Transactions on Software Engineering 35, no. 4 (2009): 573–91, https://doi.org/10.1109/TSE.2009.19. For example, extract a component dependency graph from imports and calls, then compare it with the intended architecture. The graph supplies evidence about dependencies; identifying architectural boundaries also requires interpreting the roles those components play 3.3. Joshua Garcia et al., “Obtaining Ground-Truth Software Architectures,” Proceedings of the 35th International Conference on Software Engineering (ICSE), 2013, 901–10, https://doi.org/10.1109/ICSE.2013.6606639.
- Dynamic program analysis. Analyze execution traces, logs, and test results to recover models of system behavior 45.4. Bas Cornelissen et al., “A Systematic Survey of Program Comprehension through Dynamic Analysis,” IEEE Transactions on Software Engineering 35, no. 5 (2009): 684–702, https://doi.org/10.1109/TSE.2009.28.5. Glenn Ammons et al., “Mining Specifications,” Proceedings of the 29th ACM SIGPLAN-SIGACT Symposium on Principles of Programming Languages, 2002, 4–16, https://doi.org/10.1145/503272.503275. For example, traces of job submission, retry, and completion can suggest a lifecycle state machine. The resulting model describes observed executions, which may omit important behaviors or include defects.
- Agentic program analysis. Direct a coding agent to investigate a subsystem and propose models of its architecture, behavior, or invariants. The agent can combine static and dynamic methods, following leads through source inspection, repository search, tests, and execution traces. Require evidence for each proposed relationship or behavioral claim, and distinguish observed implementation from inferred engineering intent.
- Interview engineers. Ask experienced maintainers about architectural rules, behavioral assumptions, and recurring decisions that are not adequately documented 6.6. Finn Olav Bjørnson and Torgeir Dingsøyr, “Knowledge Management in Software Engineering: A Systematic Review of Studied Concepts, Findings and Research Methods Used,” Information and Software Technology 50, no. 11 (2008): 1055–68, https://doi.org/10.1016/j.infsof.2008.03.006. Walking through a recent change or failure can expose knowledge that engineers routinely use but the implementation does not explicitly represent 7.7. Dharun Anandayuvaraj et al., “Learning From Software Failures: A Case Study at a National Space Research Center,” Proceedings of the 48th IEEE/ACM International Conference on Software Engineering (ICSE 2026), 2026, https://doi.org/10.1145/3744916.3773149. Compare this account with the recovered models and investigate disagreements about what the system does or ought to do.
These techniques produce candidate representations for engineering review. Engineers must determine which distinctions matter, whether observed behavior is intended, and which recovered models are worth maintaining. Connect the resulting models to the implementation and existing controls so that representation and enforcement can improve together.
Repeated implementation structures offer another source of candidates. A detector can narrow the search, but repetition may reflect a missing domain concept, an external protocol, test scaffolding, or ordinary cleanup. Its findings need interpretation in their architectural context.
DocAble encountered this problem through a primitive-density detector, which identifies interfaces expressed heavily through bare strings, integers, tuples, and other low-level values. Primitive density is intentionally a weak signal: such interfaces sometimes indicate that a concept is being repeatedly reconstructed rather than represented explicitly, but they are also common in perfectly legitimate code. The detector therefore produced hundreds of findings without claiming that hundreds of models were missing. Most findings needed ordinary annotations or local cleanup, or occurred in test fixtures and protocol adapters where primitive-heavy interfaces were appropriate.
A smaller subset behaved differently. Across related document mutators, the same parameter shapes recurred: language mutations repeatedly carried the same language and provenance concepts; alt-text mutations repeatedly carried description and attribution state. Looking across those instances revealed something that no individual finding established on its own. The repeated primitives expressed recurring domain concepts that the implementation had never named.
A primitive-heavy external protocol adapter may faithfully express its interface; similar primitives in internal domain code may force every consumer to reconstruct a shared concept. The question is what explains the repetition and whether naming its meaning would improve later reasoning.
Recovering a model requires more than recognizing repeated structure. Figure 4.3-1 shows the process. Weak signals identify places worth investigating; engineers then distinguish legitimate implementation structures, mechanical cleanup, and concepts worth modeling. The first two may need only an exemption or a local fix. The third calls for a change in how the system represents the concept.
Suppose a module implements a state machine through scattered conditionals and complex decision rules. Investigation reveals that several functions depend on the same states and transitions, but no shared representation defines them. The engineer can recover a state-machine model with named states, permitted transitions, and the conditions governing each transition. Making this model explicit can reveal inconsistent or missing transitions, and gives engineers a concise representation for understanding the behavior and supervising future changes. The next step is to migrate the functions that previously encoded those rules independently so that they use the shared model. Agents and codemods can perform much of this migration, while tests help establish that intended behavior is preserved.
The explicit model also makes specific rules easier to enforce. Types can restrict the states that functions accept, validators can check permitted transitions, and lints can detect code that bypasses the shared representation. The result is a stronger model substrate for subsequent engineering work. Another pass over the codebase may reveal further concepts worth recovering.
Recovering a model also creates an obligation to maintain its correspondence with the implementation. As agents migrate existing code to use the new representation, they can establish traceability relationships between model elements and the code that implements them. Static checks can then detect deleted or renamed implementation elements whose model references remain, while runtime traces can reveal modeled operations that are no longer observed or execution paths absent from the model. These checks help prevent subsequent changes from silently invalidating the recovered model. They do not establish semantic correctness, but they make discrepancies visible for investigation and, where appropriate, enforcement.
Field record — Primitive-density recovery
During the June 8–10 recovery work, findings were repeatedly reclassified as engineers resolved them. Some needed annotations or mechanical cleanup; others belonged to protocol boundaries or test fixtures and warranted exemptions. A smaller group exposed shared concepts worth modeling or design decisions that needed further judgment. The dispositions included annotate, exempt, extract a model, redesign, retire, and defer for judgment. The same weak signal thus led to several remedies; a declining finding count cannot be read as a count of recovered models.
A recovered model need not immediately govern execution or require previously separate implementations to be combined.
DocAble’s four document-processing pipelines use different engines for good reasons. PDF processing often requires inferring structure that an Office document already records. But the pipelines had also developed differences in policy, such as how much surrounding context to supply when describing an image. Those choices were embedded in separate implementations, making it difficult to determine whether their differences were intentional.
As a preliminary step, we introduced a shared policy model that recorded each format’s existing choices and linked them to the corresponding implementation. The model was initially descriptive: it let us compare policies, explain legitimate differences, and identify choices worth reconsidering. We did not merge the engines or make the model execute their policies. As we evaluate those differences, we can revise the model to reflect our engineering decisions and determine which correspondences warrant enforcement.
4.3.3 Reconcile the Map and the Territory
Before allowing a recovered model to govern later work, establish which of its claims still describe the system and which represent intended obligations.
Consider an inherited architecture wiki that no longer matches the code. Comparing the two reveals descriptions that need updating and discrepancies that may indicate defects. Verified claims can become part of a queryable model; unresolved claims remain advisory. The inset works through the judgment needed before changing either the model or the code.
SOFTWARE ENGINEERINGInset — When the model and the code disagree
Suppose a recovered architecture diagram appears to route every database access through a repository layer, but code inspection finds a direct database call. The disagreement alone does not tell you which artifact to change. There are three possibilities to investigate:
- Is the model wrong? The direct call may be an intended exception that the model omitted. Confirm the exception and represent it.
- Is the model at the wrong grain? The diagram may group several components into one service, so its arrows do not establish which internal calls pass through the repository layer. Inspect those calls before inferring a violation.
- Is the implementation wrong? If the repository boundary is an intended obligation and applies to this call, the direct call violates it. Correct the implementation.
Resolve the intended obligation and the model's scope before acting. Changing code to satisfy a mistaken model can introduce a defect; changing the model merely to match defective code can hide one. Reconciliation requires deciding which explanation fits the disagreement.
Reconciliation determines which claims need correction and which obligations should govern the implementation. Changing the implementation to satisfy those obligations is active alignment. Passive alignment then requires checks on continued correspondence; a gate can reject detected violations where enforcement is justified. Keeping the model available supports reasoning, but does not supply that check.
Even a correct rule may be unsuitable for immediate enforcement. A legacy codebase may already contain hundreds of violations. Making the rule blocking would stop development before those violations could be repaired. Instead, introduce it in three stages.
The move — Audit → Drain → Promote
- Audit. Run the new check without blocking commits. Record the violations it detects.
- Drain. Repair existing violations, using tests and other evidence to check that intended behavior is preserved.
- Promote. Once existing violations are resolved, make the check blocking so new violations it detects are rejected.
Cloudflare reports a similar practice: introduce policy checks in advisory mode, repair existing violations, and enforce them once the codebase is clean 8.8. Timo Reimann, “How Cloudflare Enforces Engineering Standards Using AI,” Cloudflare, August 4, 2026, https://blog.cloudflare.com/engineering-standards-enforcement/.
The check used to discover a problem is not always suitable for enforcement. In DocAble, primitive density helped identify code worth examining, but primitive-heavy code was not necessarily wrong. Investigation revealed more specific problems that could be prevented with types, constraints, or lints. The primitive-density detector remained advisory; the narrower checks enforced the actual obligations.
4.3.4 Invest Where It Pays
Prioritize recovery where explicit structure can reduce recurring work:
- Knowledge is repeatedly reconstructed. Engineers and agents keep re-deriving the same facts from raw implementation.
- Recurring failures expose missing structure. The same class of defect returns because nothing represents or enforces the obligation it violates.
- Consequential properties are hard to evaluate. A property that matters cannot be checked without a representation at the right grain.
- Fragmentation blocks useful joins. The facts exist, but they live in disconnected representations that cannot answer questions together.
- Recurring judgment is expensive enough to convert. A repeated human decision has become stable and frequent enough to encode.
Compare the expected loss with the cost of building and maintaining a response. Frequent reconstruction may justify a shared model; cheap recurring failures may justify a lint or procedure. Consequential failures can warrant stronger evidence or prevention even before they occur. The choice depends on recurrence, consequence, detectability, reversibility, and how stable the obligation is.
Price upkeep as well as construction. Models drift, checks require calibration, and skills age. Build the smallest asset that resolves the recurring problem, and retire it when its value no longer justifies carrying it. Chapter 6 develops this economic tradeoff; the immediate decision is which inherited structure will help the next engineering task.
Recovering one model is useful: a concept the system had been expressing for years gains a name, a representation, and perhaps an enforced obligation. Repeating the process changes something larger — the environment in which subsequent engineering occurs. Appendix B turns this recovery process into an incremental migration procedure, with exit criteria for deciding when a recovered representation or control is ready to govern subsequent work.
Works Cited
- Lehman, Meir M., and L. A. Belady. Program Evolution: Processes of Software Change. Academic Press, 1985.
- Ducasse, Stéphane, and Damien Pollet. “Software Architecture Reconstruction: A Process-Oriented Taxonomy.” IEEE Transactions on Software Engineering 35, no. 4 (2009): 573–91. https://doi.org/10.1109/TSE.2009.19.
- Garcia, Joshua, Ivo Krka, Chris Mattmann, and Nenad Medvidović. “Obtaining Ground-Truth Software Architectures.” Proceedings of the 35th International Conference on Software Engineering (ICSE), 2013, 901–10. https://doi.org/10.1109/ICSE.2013.6606639.
- Cornelissen, Bas, Andy Zaidman, Arie van Deursen, Leon Moonen, and Rainer Koschke. “A Systematic Survey of Program Comprehension through Dynamic Analysis.” IEEE Transactions on Software Engineering 35, no. 5 (2009): 684–702. https://doi.org/10.1109/TSE.2009.28.
- Ammons, Glenn, Rastislav Bodík, and James R. Larus. “Mining Specifications.” Proceedings of the 29th ACM SIGPLAN-SIGACT Symposium on Principles of Programming Languages, 2002, 4–16. https://doi.org/10.1145/503272.503275.
- Bjørnson, Finn Olav, and Torgeir Dingsøyr. “Knowledge Management in Software Engineering: A Systematic Review of Studied Concepts, Findings and Research Methods Used.” Information and Software Technology 50, no. 11 (2008): 1055–68. https://doi.org/10.1016/j.infsof.2008.03.006.
- Anandayuvaraj, Dharun, Tanmay Singla, Zain A. H. Hammadeh, Andreas Lund, Alexandra Holloway, and James C. Davis. “Learning From Software Failures: A Case Study at a National Space Research Center.” Proceedings of the 48th IEEE/ACM International Conference on Software Engineering (ICSE 2026), 2026. https://doi.org/10.1145/3744916.3773149.
- Reimann, Timo. “How Cloudflare Enforces Engineering Standards Using AI.” Cloudflare, August 4, 2026. https://blog.cloudflare.com/engineering-standards-enforcement/.