The engineering documentation standards decision record: why the standards model you chose determines your documentation quality floor and your knowledge transfer overhead rate

A 19-person developer tools startup had been building a CLI-based deployment platform for three years. The engineering team of eight had grown organically from the two founders: knowledge transfer happened in real time during pair programming sessions and Slack threads, and the founding engineers shared enough context that explicit documentation had never been a bottleneck. The VP Engineering joined at headcount twelve and observed that documentation existed across three surfaces simultaneously: a Confluence instance containing high-level architecture diagrams written during a Series A due diligence process, a Notion workspace that two engineers had started using for project notes and that had accumulated roughly 140 pages over eighteen months, and README files in each repository describing setup instructions. No canonical source had been designated. No documentation standard had been written. No one had decided which system was authoritative for which class of information.

The most senior engineer on the team — one of the two founders — had been the primary maintainer of three critical integrations: the credential provider handling customer authentication tokens, the pipeline event bus coordinating deployments across the customer's infrastructure components, and the retry logic embedded in the CLI's deployment executor. She had documented none of these in Confluence, one partially in a Notion page she used as a personal scratchpad, and the retry logic in a series of Slack threads where she had explained the specific edge cases to other engineers over two years. At month thirty-two she accepted a competing offer and gave three weeks' notice.

The replacement engineer started at month thirty-five. Her onboarding goal was to be able to independently make changes to the three critical integrations within six weeks — the timeline the VP Engineering had estimated based on onboarding previous engineers for less complex systems. The actual timeline was fourteen weeks. The Confluence architecture diagrams described the credential provider at the level of abstraction present in the original Series A deck — correct at the block-diagram level, missing the operational detail governing how authentication tokens were refreshed, which edge cases triggered fallback behavior, and what the consequence was of the fallback path being taken more than twice in a fifteen-minute window. That consequence: rate limiting at the customer's identity provider that manifested as a silent authentication failure rather than an error code. The Notion page described an earlier version of the credential provider predating a refactor eighteen months prior and contained constraints that were no longer operative. The Slack threads describing the retry logic were unreachable: the company had changed its Slack tier between month eighteen and month thirty and the message history retention policy had deleted threads older than twelve months.

The replacement engineer discovered the fourteen-week timeline's cause at week eight, when she made a change to the credential provider's token refresh path based on the Confluence documentation and the Notion page — neither of which mentioned the rate-limiting edge case — and a customer triggered the silent authentication failure in a production deployment. The incident investigation required three engineers spending two days reconstructing the constraint reasoning from git commit messages, code comments, and one email chain found in the original engineer's sent folder. The constraint had been known and deliberately handled; it had never been written in a document the next engineer would find. Connect this to the engineering knowledge management decision record: the documentation gap is not a failure of engineering culture or individual diligence — the departing engineer documented her thinking consistently, in the tools and formats she found natural; the failure is a standards model that never designated a canonical location, never specified what level of operational detail was required for critical integration documentation, and never connected the "document your work" norm to a quality criterion or a review gate that would have surfaced the gap before the departure rather than after the incident.

The VP Engineering's post-incident response was to declare Notion as the canonical documentation system and begin a documentation audit. The audit found that three other engineers had each developed personal documentation practices on different surfaces, and that the transition to "Notion is canonical" had produced a fourth surface without resolving the other three. Four months after the incident, the credential provider's documentation in Notion was complete and accurate, maintained by the replacement engineer who had written it during her onboarding work. The other three engineers' personal documentation remained where it had been. The audit had produced the right insight — canonical source designation is necessary — but had not produced the operational change required: a standard specifying what must be documented, in what format, at what quality level, maintained by whom, and enforced through what review gate.

A 41-person B2B SaaS building a customer data platform had an engineering organization of 22 engineers across four product teams. At headcount eighteen, the VP Engineering had announced at an all-hands meeting that "going forward, all technical documentation lives in Confluence." The announcement was accompanied by a Confluence space structure: one space per team, a shared Architecture space, and a Runbooks space for operational procedures. No documentation template was defined. No quality criteria were specified. No review gate was established. The standard was a location designation without an operational model for what documentation was expected to contain or how it was expected to be produced.

Eighteen months after the announcement, the VP Engineering commissioned a documentation audit in preparation for a Series B due diligence process. The audit found 312 pages in the Confluence instance. Coverage by engineering team: all four teams had at least one page per service. The audit's second pass was more revealing. Of the 312 pages: 73% were in Draft status — Confluence's default status; none had been explicitly published as complete. Twelve had been given explicit Outdated status labels by engineers who had reviewed them and found them stale, with no link to current documentation or indication of what had changed. The most recent meaningful edit to any page in the Architecture space had been made 14 months prior. Meaningful edit was defined in the audit methodology as an edit adding more than 50 words to the page body — edits that added a sentence or updated a date had been excluded from this metric.

The specific failure that triggered the audit commission was a product manager's experience preparing requirements for a new feature that would extend the customer data platform's event ingestion pipeline. She had spent three days in Confluence attempting to understand the constraints on the ingestion pipeline: what the maximum event payload size was, what happened to events that exceeded the size limit, whether the pipeline had retry semantics and if so at what delivery guarantee level, and what the latency distribution looked like between event ingestion and downstream availability to the query layer. She had found three pages describing the ingestion pipeline — one written 28 months ago during an initial architecture session, one written 16 months ago describing a refactor, and one written 8 months ago that appeared to be an incomplete draft. The three pages were inconsistent on two of the four questions she had. The 28-month-old page specified a 256 KB payload limit. The 16-month-old refactor page mentioned that the payload limit had been increased "as part of this refactor" without specifying the new value. The 8-month-old draft page had a placeholder where the payload limit should have been.

She found the current payload limit by asking the engineer who had written the 8-month-old draft page in a Slack message. The answer — 2 MB — was accurate. The engineer also told her that the 16-month-old refactor had changed the delivery guarantee from at-most-once to at-least-once, which was not documented anywhere in Confluence. She incorporated this information into her requirements document and noted in a comment that the Confluence documentation was unreliable and that the Slack message was the source. Connect this to the technical debt quantification decision record: the documentation debt in this scenario is not a deficit that appears in any technical debt register; there is no metric showing "18 engineers are spending 4 hours per sprint on archaeology because documentation quality is below the threshold at which it can be trusted"; the cost is distributed across every engineer who asks a question to a person that documentation could have answered, every product manager who includes a comment noting that Confluence is unreliable, and every new engineer who learns during onboarding to ask people rather than read documentation — accumulating invisibly until a due diligence process, a departure, or an incident makes the overhead visible.

The documentation standard that would have prevented this failure required four operational elements that the all-hands announcement had not provided. A template specifying what questions each section type was responsible for answering — not a list of section headings, but a set of questions like "what are the constraints on input payload (size, schema, encoding)?" and "what are the delivery guarantee semantics and how are failures surfaced?" that a documentation author was expected to answer in the relevant section. An acceptance criterion defining when a page moved from draft to published — specifically, a criterion requiring answers to the template questions rather than presence of section headings. A review gate requiring a second engineer to verify that the answers to the template questions were accurate and complete before the page was marked published. And an ownership assignment requiring a named engineer to confirm accuracy after any change to the component the page documented. The tool — Confluence — was correct for the team's size and workflow. The standard was what was missing.

A 67-person enterprise SaaS building a healthcare analytics platform had an engineering organization of 34 engineers and a documentation standard written by the platform team lead and the VP Engineering at month twelve: a 12-section documentation template covering system overview, architecture diagram, external dependencies, data models, API contracts, configuration management, deployment model, observability and alerting, known limitations, decision rationale, operating procedures, and change history. The template was accompanied by a documentation review checklist specifying that all 12 sections must be present and non-empty for a documentation page to pass review. The checklist was implemented as a pull request requirement: documentation PRs were assigned to a documentation reviewer who checked section coverage. The coverage metric was tracked quarterly and reported in engineering leadership meetings. At month thirty, the coverage metric was 89% across 41 active services.

The metric masked a quality problem invisible to coverage measurement. At month thirty, a third-party authentication service the platform had used for three years announced API deprecation with a six-month migration window. The analytics platform's authentication service would need to be rewritten. The VP Engineering assigned three engineers to the rebuild and pointed them to the authentication service's documentation as the starting point for understanding what the current service did and why it had been built the way it had. The documentation page had all 12 sections and was marked as published following a review that had verified section coverage two years prior.

The rebuild engineers spent week one reading the documentation. Their findings: the system overview section was two paragraphs describing the authentication service at the same level of abstraction visible from the API contract — accurate, but not informative about the internal design. The architecture diagram section contained a link to a diagram in Lucidchart that required login credentials disabled when the team had moved from individual to shared accounts. The external dependencies section listed five dependencies with version numbers but no rationale for each dependency's inclusion — no explanation of what alternatives had been considered or why these were chosen. The decision rationale section — the section most directly addressing "why is this built this way?" — contained eleven items, nine of which were one sentence beginning with "Best approach for the problem," "Most appropriate for our use case," or "Standard practice in the industry." The two exceptions were a rationale for the token expiry window ("24-hour expiry chosen to balance security against user session interruption frequency — internal research found users tolerated re-authentication at session start but found mid-session interruptions disruptive") and a rationale for the retry model ("three retries with exponential backoff chosen after load testing revealed identity provider rate limits at 50 requests per minute; the retry model caps burst request rates at 45 requests per minute under worst-case timing"). The other nine rationale entries were section-filling text without reasoning content.

The rebuild team spent three weeks in archaeology before writing a line of new code. The archaeology work: reading 36 months of commit history to reconstruct which design decisions were intentional versus accidental, consulting three engineers who had worked on the original service, reviewing incident post-mortems for the authentication service, and auditing the dependency choices by reading dependency documentation to reconstruct why each had been selected. The archaeology produced four discoveries the documentation had not contained: the identity provider's rate limiting behavior (documented correctly in the two good rationale entries, but the rebuild team would not have found it without those entries pointing them to look); a behavioral difference between the production identity provider and the test environment stub that had caused two incidents and had been worked around with a conditional in the authentication service that would need to be replicated or the workaround would be missing; a data residency constraint requiring authentication tokens to be validated within a specific geographic region, embedded as a configuration constant whose name did not indicate its purpose; and a compliance requirement that authentication events be logged at a specific verbosity level with specific field names for audit trail purposes, documented only in a comment in the logging configuration file. Connect this to the platform team charter decision record: the documentation standard had been operationalized correctly in terms of format and review process but had been defined with a quality metric — section coverage — that was measurable at low cost rather than with quality criteria evaluable at the cost of reviewer judgment; the nine one-sentence decision rationale entries had all passed the checklist review because the checklist checked presence, not reasoning depth; a quality criterion requiring each rationale entry to include the specific alternative considered and the specific evidence or reasoning that favored the chosen approach over the alternative would have required more reviewer effort but would have prevented the nine content-free entries from passing review.

The rebuild team reproduced three of the four undocumented constraints in their new implementation: the behavioral difference with the test environment stub, the data residency constraint (discovered by an alert during load testing in the staging environment), and the compliance logging requirement (discovered during an internal security review three weeks after the service deployed to production). The fourth constraint — the identity provider rate limiting behavior — was reproduced correctly because it was in the two good rationale entries and the rebuild team had read them. That constraint was also the most subtle: without the rationale entry, the rebuild engineers would likely have set a default retry model, discovered the rate limiting in production under high load, and debugged a silent authentication failure pattern the original team had already solved. Connect this to the technical roadmap prioritization decision record: the rebuild team's three-week archaeology delay and the post-deploy security review finding are not visible in the roadmap as documentation debt; they appear as "rebuild taking longer than estimated" and "security review finding requiring a hotfix"; the causal chain from documentation quality standard to rebuild timeline to security review finding is not traced in any single artifact; and the investment required to prevent it — a documentation quality criterion requiring reasoning depth in the decision rationale section, evaluated by a reviewer at time of initial documentation — is a one-time investment that pays compound returns across every future engineer who reads the documentation and every future system change that builds on the constraint reasoning captured there.

Structural properties set by the documentation standards decision

Two structural properties are determined by the founding decisions about what documentation must contain, how quality is defined and enforced, and how documentation currency is maintained after initial creation. Neither property is visible in documentation coverage metrics or tool adoption rates until a departure reveals that critical knowledge lived only in personal Slack threads, a service rebuild team discovers that 89% coverage contained almost no reasoning, or an incident investigation reconstructs in two days what a complete documentation record would have made available in two minutes.

Property 1: Documentation quality floor. The documentation quality floor is the minimum level of documentation quality reliably produced by a given standards model under normal engineering time pressure — not the maximum from excellent engineers who document thoroughly when given adequate time, but the floor below which documentation reliably falls when engineers are constrained by sprint commitments and documentation is not enforced at a quality level through review gates. The floor is set by three decisions. First, whether the quality criteria specify reasoning depth requirements or only format requirements. A format-only standard — sections must be present — produces a floor of section presence without reasoning content; the 67-person enterprise SaaS example illustrates this precisely: 89% coverage, almost no reasoning. A reasoning-depth standard — each decision rationale entry must name the specific alternative considered and the specific evidence or constraint that favored the chosen approach — produces a floor of reasoning content in addition to section presence; the floor is lower than the ceiling from excellent documentation, but it is substantially higher than section-filling text. Second, whether the review gate evaluates reasoning depth or section coverage. A review gate evaluating section coverage can be operationalized as a checklist, is fast to execute, and produces a floor of section presence; a review gate evaluating reasoning depth requires reviewer judgment about whether the reasoning in each section is sufficient for the documentation's purpose, takes longer, and requires the reviewer to know enough about the system to evaluate whether the reasoning is complete. The cost difference is real; the value difference is larger. Third, whether documentation is treated as a work product with acceptance criteria evaluated before the feature is considered complete. Documentation produced after a feature ships, as a separate activity without a corresponding review gate, will be produced by engineers whose attention has shifted to the next feature; the floor for documentation produced as part of feature delivery, with a review gate on the feature branch, is significantly higher because the constraint reasoning is most accessible to the engineer who just built the feature and degrades with time as attention shifts. The practical implication: a documentation standard requiring a documentation review as a pull request requirement on the feature branch — not a separate PR after the feature ships — produces a meaningfully higher quality floor than a standard requiring documentation "as soon as possible after the feature ships."

Property 2: Knowledge transfer overhead rate. The knowledge transfer overhead rate is the fraction of engineering capacity consumed by activities required because documented knowledge does not exist, cannot be trusted, or requires archaeology to access. The activities include: onboarding time beyond what would be required with complete, current, accurate documentation; incident investigation time spent reconstructing constraint context that documentation should have made accessible; and product and engineering planning time spent verifying that documented constraints are still accurate rather than proceeding with confidence in the documentation's currency. The rate is not tracked as a metric in most engineering organizations — it is distributed across activities logged as "onboarding," "investigation," and "planning" rather than as "documentation gap costs." The rate is inversely related to the documentation quality floor: a higher floor reduces the archaeology required during incident investigation, reduces onboarding time for engineers inheriting systems, and reduces the verification overhead product managers experience when building on documented constraints. The accumulation model is non-linear: the overhead rate is low and approximately constant in the early months of an engineering organization when engineers share enough context that knowledge gaps are filled by asking colleagues; the rate increases as the organization grows because the ratio of questions-that-can-be-answered-by-asking to questions-that-require-documentation shifts toward documentation as the number of engineers grows; and the rate accelerates discontinuously at departure events — each senior engineer departure removes knowledge that will either be reconstructed at significant cost or lost and discovered missing later at higher cost. The 19-person startup example: the three-week-to-fourteen-week onboarding gap for the replacement engineer represents the accumulated overhead of three years of documentation decisions that prioritized individual productivity over documentation standards; the cost of the documentation standard that would have prevented it was the time required to designate a canonical documentation surface and write quality criteria for critical integration documentation — a one-time investment measurable in hours, not weeks.

The engineering documentation standards ADR: five sections

Section 1: Documentation scope definition and required artifact types. The scope definition specifies what must be documented, at what level of detail, in what canonical location, with what artifact type for each documentation class. The scope should enumerate by documentation class rather than by team or system: services require a service documentation artifact covering operational and constraint context; data models require a schema documentation artifact covering field semantics and constraint reasoning; integration points with external systems require an integration documentation artifact covering operational constraints and failure modes; architecture decisions require a decision record artifact separate from service documentation, because decisions outlive the services they shaped. The canonical location designation should be a single source for each artifact type — not a designation of one tool for all documentation, which produces the startup example's multi-surface fragmentation without a clear decision about which surface is authoritative, but an explicit mapping from artifact type to canonical location: service documentation in X, decision records in Y, runbooks in Z. The scope definition should also specify what does not require documentation at the specified quality level — low-complexity utility libraries, scripts with complete README coverage of their behavior, internal tooling used by fewer than three engineers — because an exhaustive documentation requirement for all code produces either selective compliance (engineers document the high-complexity systems and skip the low-complexity utilities) or box-checking compliance (engineers document everything at the minimum quality level required to pass the review gate, regardless of complexity). The scope definition establishes the boundaries within which quality criteria and review gates operate.

Section 2: Quality criteria and completeness definition. The quality criteria specify what a documentation artifact must contain to be considered complete — not which sections must be present, but what questions each section must answer. For a service documentation artifact, the questions are concrete: what are the constraints on input (size, schema, encoding, rate limits), what are the delivery guarantee semantics and how are failures surfaced, what are the operational failure modes and how is each handled, what are the external system dependencies and what behavior does the service exhibit when each dependency is unavailable, what are the security and compliance requirements and how are they implemented? For a decision record artifact, the questions are similarly concrete: what was the decision made, what alternatives were considered, what was the specific reasoning or evidence that favored the chosen approach over each alternative, what were the constraints that shaped the decision (timeline, team capability, budget, compliance requirement), and under what conditions should this decision be revisited? The quality criteria should include examples of acceptable and unacceptable answers for each question type — not because engineers need to be told how to document, but because the boundary between "sufficiently complete" and "not sufficiently complete" is ambiguous without examples, and a reviewer evaluating documentation quality needs a calibration reference. The enterprise SaaS example's nine one-sentence decision rationale entries each satisfied a quality criterion of "non-empty" and none satisfied a quality criterion of "names the specific alternative considered and the specific evidence favoring the chosen approach over the alternative." The difference between these two criteria is not subjectivity — the one-sentence entries are verifiably noncompliant with the second criterion — it is the specificity of what the criterion requires.

Section 3: Documentation review model. The documentation review model specifies when documentation is reviewed, by whom, and what the acceptance criteria for the review are. The review model should be integrated into the feature delivery process rather than appended to it: documentation review as a pull request requirement on the feature branch, not a separate activity after the feature ships. The reviewer role should be specified — not a documentation team reviewer, but the second engineer most familiar with the system being documented, because quality evaluation requires familiarity with what the documentation claims; a reviewer who does not know the system cannot verify that the decision rationale is complete or that the constraint description is accurate. The acceptance criteria for a documentation review should be defined explicitly: not "documentation is complete" (which is the format-completion standard the enterprise SaaS example had), but "each required question in the quality criteria is answered at sufficient depth for an engineer unfamiliar with this system to understand the constraint without asking a follow-up question." The review should flag specific sections where the answer does not meet this criterion, with a specific question identifying what additional reasoning is needed. A review comment saying "decision rationale item 3: what was the alternative to JWT tokens that was considered? the entry says 'JWT tokens are the best approach' but doesn't name the alternative" is actionable; a review comment saying "decision rationale needs more detail" is not. Connect this to the engineering knowledge management decision record: the review model is the operational mechanism that converts a documentation quality standard from aspiration into outcome; engineering organizations that have the standard but not the review model produce the 41-person SaaS outcome — 73% draft status, no accepted documentation, documentation archaeology as the reliable path to accurate answers — because the standard without enforcement produces documentation quality calibrated to the minimum required to be considered done, which in the absence of a review gate is whatever the engineer produces when sprint pressure is highest.

Section 4: Living documentation model and currency maintenance. The living documentation model specifies how documentation remains current after the initial creation event. The model should address three mechanisms. Ownership assignment: each documentation artifact has a named owner responsible for its currency — specifically, the engineer currently most responsible for the system the artifact documents, updated when ownership changes. The owner's responsibility is not to write all updates but to ensure that changes to the system are reflected in the documentation within a defined window: typically within the sprint in which the change ships. Change-triggered review: any pull request changing a system should include a documentation review step verifying whether the change requires a documentation update, and if so, includes the update or creates a follow-up item with an explicit deadline rather than leaving the update unscheduled. The follow-up item model is weaker than the in-PR update model but is appropriate for changes whose documentation implications require investigation rather than straightforward update. Staleness signaling: documentation that has not been reviewed by its owner within a defined period — 90 days is a reasonable default for service documentation at the 20-50 engineer scale — should carry a visible staleness indicator accessible to any engineer reading the documentation, with a clear path to the current owner for verification or update. The staleness signal is not a shame indicator; it is a reliability indicator that helps engineers calibrate how much to trust the documentation they are reading. The 41-person SaaS example had 12 pages with Outdated status labels that linked to nothing; this is the staleness signal without the resolution path. A complete staleness model includes the signal, the owner contact, and either a current version link or an explicit deprecation note that closes the staleness loop rather than leaving it open.

Section 5: Documentation debt measurement and remediation model. The documentation debt model specifies how to detect existing documentation gaps, quantify their cost, prioritize remediation, and prevent re-accumulation. Detection: the documentation audit is the standard mechanism, but an audit produces a point-in-time snapshot requiring periodic re-execution rather than continuous visibility. A lightweight continuous detection mechanism is query frequency tracking — counting how many times engineers ask specific questions in Slack or in code review that documentation should have answered, and using the question frequency as a proxy for documentation value: systems generating high question volume are high-priority documentation targets regardless of what the coverage metric shows. Cost quantification: the documentation debt for a given system is most accurately quantified by sampling the onboarding time for engineers who needed to understand that system, the investigation time for incidents involving that system, and the planning time for features touching that system — and comparing those times against a baseline for what the same activities would require with complete, accurate documentation. Remediation prioritization: documentation debt remediation should be prioritized by the combination of query frequency and change frequency — systems that engineers frequently need to understand and that are actively changing are both higher-documentation-value and higher-staleness-risk targets; stable systems engineers rarely query are low-priority remediation targets even if their documentation is known to be poor. Prevention: the review model in Section 3 is the primary prevention mechanism; documentation debt accumulates when new features and systems are created without documentation review gates, and the remediation cost of catching up is always higher than the creation cost of documenting at time of development. Running the AI chat sessions in which system design and constraint reasoning were worked out through the open-source extractor is the highest-leverage remediation path for decisions whose reasoning was never formally documented: if an engineer worked through the design of the authentication service's retry model in a Claude session, the session contains the reasoning — alternative retry strategies considered, load testing results that revealed the rate limiting constraint, the specific constant chosen and why — that the decision rationale section should have captured; extracting it from the chat history is faster than reconstructing it from commit messages and code comments, and produces a documentation artifact grounded in the actual constraint reasoning rather than a reconstruction that may miss the specific evidence that drove the decision.

FAQ

Further reading

• Engineering knowledge management decision record — documentation standards are the operational mechanism implementing a knowledge management strategy; the knowledge management decision determines what categories of knowledge the engineering organization is responsible for capturing and maintaining; the documentation standards decision determines how capture is enforced and what quality floor the enforcement model produces; without a quality floor set by the standards model, the knowledge management strategy produces the 41-person SaaS outcome: documentation exists in the designated system, counts correctly in the coverage metric, and is systematically unreliable as an information source because the standard never specified what "complete" meant for documentation intended to answer specific engineering questions.
• Technical debt quantification decision record — documentation debt is a category of technical debt whose cost is particularly invisible to standard quantification models: the cost of a missing architecture constraint is not a slow test suite or a deployment delay but an archaeology session that three engineers spend two days on to reconstruct what a complete documentation record would have made accessible in two minutes; a debt quantification model that excludes documentation gaps systematically underestimates the total cost of debt and systematically deprioritizes documentation remediation relative to code complexity or dependency currency work whose costs are more directly measurable.
• Platform team charter decision record — platform team charters are one of the highest-value documentation targets in an engineering organization, because they contain the scope boundary rationale, adoption model tradeoffs, and demand model design that becomes inaccessible when the engineers who negotiated the charter move on; a documentation standard applied specifically to charter documents — requiring that scope boundary decisions include the alternatives considered and the demand signals that motivated the boundary — is a specific and high-leverage instance of the broader reasoning-depth quality criterion; the "that's not in our current charter" response that produced two parallel infrastructure paradigms in the enterprise SaaS example would have been accompanied by a charter extension process rather than a scope exclusion if the charter document had contained the reasoning explaining what organizational signal was supposed to trigger a charter review.
• Technical roadmap prioritization decision record — documentation quality affects roadmap prioritization quality through two paths: engineers making prioritization decisions without access to the constraint reasoning from prior decisions reproduce the same tradeoff analysis the original authors performed, at the cost of sprint time and without the benefit of the original authors' information; and the absence of documented constraint reasoning produces roadmap items motivated by "we don't know why the current architecture is this way" — archaeology items that would not exist if the original documentation had captured the constraint reasoning — which consume prioritization capacity that could be directed at new capability investments; the documentation standard that prevents reasoning-free entries in decision rationale sections is also the standard that prevents archaeology-motivated roadmap items from becoming the default mode of technical investment planning.
• Open-source extractor — the AI chat sessions in which engineers worked through the design decisions, constraint analysis, and alternative evaluations that shaped a system's architecture are the primary source for the reasoning that documentation should have captured and frequently did not; the startup engineer who reasoned through the credential provider's rate limiting behavior in a Claude session, the enterprise SaaS team that evaluated authentication token strategies in a series of ChatGPT conversations before writing the first line of code — these sessions contain the constraint reasoning that the documentation standards review gate should have required and that three weeks of archaeology was required to partially reconstruct; running those sessions through the extractor before a system rebuild or a documentation remediation sprint produces the specific reasoning — alternatives considered, constraints encountered, decisions made — that a documentation quality standard exists to capture and that is most efficiently recovered from the AI chat history rather than reconstructed from commit messages, code comments, and engineer interviews.