Ingest: In defense of not understanding your codebase
Type: types/ingest-report.md
Classification
An argumentative essay supported by practitioner recollections rather than a systematic study. Author: Sean Goedecke, who reports personally taking ownership of abandoned codebases and recovering enough understanding to modify them. That experience gives the argument a concrete basis, but the essay supplies no independently inspectable recovery cases.
Summary
Goedecke argues that partial, fallible understanding is a normal operating condition in large, high-turnover software systems, not a reason to stop useful work. Against his reading of Naur's recommendation to discard programs whose original theory has been lost, he offers two objections: accumulated production quirks make wholesale reconstruction impractical, and successors can acquire useful understanding of abandoned systems. His suggested route is to trace one flow end-to-end, make careful changes, and gradually expand the area understood. Maintaining a comprehensible theory competes with other obligations, including product requirements, security, and legal compliance. A brief discussion suggests LLMs might accelerate partial understanding while impeding detailed understanding, but explicitly leaves that trade-off unresolved.
Quotes
No source quotes have been retained yet.
Connections Found
The essay is a practitioner counterpoint to treating lost understanding as grounds for wholesale replacement. Its most useful connection is to Design rationale must preserve decision premises its interpreter cannot regenerate: recovering enough understanding to make changes is not the same as faithfully recovering the original decision premises. Goedecke's reported successes challenge an absolute practical impossibility claim, but do not show that missing intent, warrant, or historical alternatives can be recovered from code. For Commonplace, the connection narrows the retention question: preserve premises a successor needs but cannot recover, rather than requiring complete understanding before any work can proceed.
Learning Claims (our opinion)
The proposed mechanism is human learning through source inspection and incremental work: understand one flow, act on that understanding, then expand it. Relative to the theory-builder definition, the mapping is incomplete. Localized content: code is available, but the essay does not show that the engineer's explanatory theory is stated in identifiable units; its intuitive understanding need not meet this condition. Consumption: the account plausibly describes understanding guiding changes, without traces that isolate its effect. Content-directed criticism: educated guesses and dealing with consequences suggest opportunities for correction, but no stated criticism aimed at a particular explanatory claim is documented. Iteration: gradual expansion implies retained understanding shaping later work, but the essay gives no sequence showing a criticism producing a revision used in the next round. Persistence is reported across work on the same codebase; transfer across engineers or unrelated problems is not established.
The author reports improved capacity to work on abandoned systems. This is anecdotal support for learning, independently of whether the process meets Commonplace's four conditions. It supports distinguishing adequate successor understanding from exact recovery of predecessor understanding; it does not establish an LLM learning mechanism or justify weakening the localized-content requirement. There is no controlled comparison of recovery workflows, retained representations, or system boundaries, so the reported success does not select a preferred KB architecture.
Extractable Value
- Separate operational recovery from historical recovery. A successor may become able to change a system without recovering its original decision premises. This distinction qualifies how the existing rationale-retention note should use successful revival stories: they challenge mandatory rewrites, not the need to retain otherwise unavailable premises. [quick-win]
- Use one end-to-end flow as a recovery starting point. The essay offers a concrete practitioner heuristic for rebuilding useful local understanding before attempting broad coverage. For agent-operated KBs, this is a candidate workflow to test, not evidence that selective inspection already suffices for reliable maintenance. [experiment]
Limitations (our opinion)
The central revival claim rests on the author's recollections, without named systems, task histories, failure rates, or a comparison against rewrites. Those accounts make recovery plausible but cannot establish how often it succeeds or which supporting conditions are necessary. The scale argument does not establish that all large systems are impossible to rewrite; the essay itself allows incremental replacement. Its criticism targets a strong reading of Naur, and successful maintenance under a new partial understanding does not by itself refute claims about recovering the original theory. As the rationale-retention note explains, plausible substitute explanations can enable action while leaving historical premises unavailable. The essay also gives no criterion for when partial understanding is sufficient for a particular change's risk. Its LLM paragraph is conjectural and should not be used as evidence that LLM assistance improves understanding or maintenance outcomes.
Recommended Next Action
Review kb/notes/design-rationale-must-preserve-unregenerable-decision-premises.md against this practitioner counterpoint, checking that it keeps useful successor understanding distinct from faithful recovery of historical decision premises.