Rationale as a Dated Record: Where the Why Lives for the Next Reader

Sources#

The questions#

Three #oq/now items that each carry a Partially answered pointer to Where Does the Why Live?. That page settled the authoring-time half, where the why is well-homed, and left the read-time half as "nowhere durable, by default it evaporates":

Building Is Cheap, Arguing Is Expensive: if design discussion lives in PRs and prototypes, where is the rationale recorded for future readers? Does the "why we chose this" knowledge survive, or does it share the staleness problem of Code as Source of Truth?
Prototype Over PRD: if there is no PRD, where does the rationale ("why we chose variation B") live for future readers? Its residual is whether a durable read-time home exists that doesn't reintroduce the PRD.
Code as Source of Truth: what knowledge genuinely can't live in the codebase (org strategy, the "why", cross-team context) and therefore still needs a durable doc, and how do you keep that small slice current?

Since June the vault has gained three things the earlier page did not have: the authority analysis in Is Persistence the Line Between Prompting and Spec-Driven Development?, the committed intent.md in The Committed-Artifact Chain, and the Codex team's checked-in decision logs. The Codex account was already ingested, but its decision-log sentence was never carried into Agent Harness Engineering. Together they close the first two questions and narrow the third.

The reframe: rationale is history, and history does not go stale#

Question 1 offers two outcomes: rationale either doesn't survive, or survives and goes stale like any doc outside the update loop. That choice assumes rationale is the same kind of claim as a spec. It isn't.

What staleness is. Code as Source of Truth explains why docs decay: code changes faster than any doc outside the update loop, so a doc's present-tense claims about the system stop being true. Is Persistence the Line Between Prompting and Spec-Driven Development? adds that the harm needs a read-back. Pocock deletes PRDs because an agent finds a stale document and is misled by it, and a stale document only misleads when something reads it back as current.
What rationale is. "On date T, with options A and B on the table, we chose B because X" is a claim about a past event. The code can change completely and the claim stays true. What changes is only whether the decision still governs.
So the failure mode is different. A dated decision record can be lost, and it can be mistaken for current authority. It cannot go stale. The corpus already has the discipline that handles the second risk. Pocock closes the PRD's GitHub issue instead of deleting it: "I just mark it as closed. It can fetch it if it wants to, but it's got a visual indicator that it's done" (Full Walkthrough: Workflow for AI Coding — Matt Pocock, read on Is Persistence the Line Between Prompting and Spec-Driven Development? as "authority revoked, file kept").

The honest answer to Question 1's disjunction is therefore neither, conditionally. Left in merged PR threads and a deleted PRD, the why is orphaned, and Where Does the Why Live? stands on that. Written down as a dated record beside the code, it survives and is immune to the drift problem, as long as someone marks it superseded when a later decision overturns it.

Where the corpus actually records it (read-time homes, in practice)#

The earlier page found only two partial patches, both conceptual: a richer HTML artifact and a compiled knowledge base. The corpus now holds named, practised homes.

Home	What it holds	Status in the source	Source
Execution plans with decision logs, checked into the repo	"complex work is captured in execution plans with progress and decision logs that are checked into the repository. Active plans, completed plans, and known technical debt are all versioned and co-located"	Run in production by OpenAI's Codex team: ~1M lines, ~1,500 PRs, 3–7 engineers, five months. First-party account, and no measurement of whether the logs get read	Harness engineering: leveraging Codex in an agent-first world, Agent Harness Engineering
`intent.md` as the first committed artifact	specified to carry "what is wanted, why, and under which constraints" in the originator's own words, with the commit chain "also the audit trail: who asked for what… who approved it"	Prescription only, `vendor-claim`, no measurement of any kind	The Committed-Artifact Chain
The closed issue	the PRD kept after implementation with its authority revoked	One practitioner's workflow	Full Walkthrough: Workflow for AI Coding — Matt Pocock, Design Concept Grilling
ADRs authored by an agent skill	an `adr-template` skill that "author[s] and maintain[s] Architecture Decision Records… to preserve engineering context"	A frontmatter example in a vendor tutorial, not a reported deployment	Enable on-demand expertise with Agent Skills in Genkit Go

One trace result shows that agents do read this genre in real sessions. It is a small share, but it is not zero. Gao & Chen count 120 Architecture/ADR events, 4.0% of 3,033 documentation interactions across 557 real agentic coding sessions, and plans and working notes form the second-largest genre at 25.1% (Agent Documentation Behavior). That settles only one point: a committed decision record lies on a path agents actually traverse. It does not measure whether reading one changes a later decision.

The Codex account also states the premise behind the whole move. "Knowledge that lives in Google Docs, chat threads, or people's heads [is] not accessible to the system… anything it can't access in-context while running effectively doesn't exist." Rationale left in PR discussion is the chat-thread case: stored, but not placed where a future reader, human or agent, will look.

The where is a dated decision record co-located with the code it explains: a decision log inside the execution plan (Codex), the intent.md that opens the chain (The Committed-Artifact Chain), or an ADR. The default build-to-decide practice, three PRs compared and one merged (Building Is Cheap, Arguing Is Expensive), leaves the why in the losing PRs' threads and the reviewers' heads. Build-to-decide is fixed by adding one step: when you merge the winner, write the comparison verdict into the decision log. Of the three, only the decision log and the ADR are written after the choice; intent.md is written before the build, so it holds the why of the request, not the why of the variant that won.

On staleness, the answer is no, for the reason in the reframe above. A decision record makes no present-tense claim about the code, so code churn cannot falsify it. The drift mechanism that forces Code as Source of Truth to pull specs into the repo does not apply. The residual hazard is different: a superseded decision read as still binding. The corpus has a named practice for that (close, don't delete) and a named rule (name exactly one source of truth per artifact, Code as Source of Truth's August 2026 section).

Verdict: settled as posed. Where the rationale lives: a committed dated decision record, which by default it does not get. Whether it survives: only if written there. Whether it shares the staleness problem: no, because staleness is a property of present-tense claims. The failure it does share is getting lost. Question 1's other #oq/source sibling, about when generate-three stops paying, is unaffected.

Answer 2: the read-time home is not a PRD, because a PRD is defined by authority and a decision record has none#

Prototype Over PRD's residual was whether any durable read-time home exists that doesn't bring the PRD back through the side door. Is Persistence the Line Between Prompting and Spec-Driven Development? gives the criterion to test this: an artifact is a spec when later work is judged against it. The PRD did three jobs, alignment, specification and rationale (The PRD-Replacement Spectrum at AI-Native Speed). What made it a PRD rather than a memo was the specification job, the authority it held over the build.

A decision record carries only the third job, and by construction it holds no authority:

It is written after the choice, so no build is judged against it. The prototype remains the spec (Prototype Over PRD).
It is backward-looking: "variation B beat A because users could do X in one step". It is not "the system shall…".
When a later decision overturns it, it is closed rather than obeyed, the Pocock pattern. This is exactly the authority revocation that separates a kept record from a live spec.

intent.md does not pass this test, and so it is not an answer to this question. Is Persistence the Line Between Prompting and Spec-Driven Development? groups it with the destination PRD as an artifact that binds later human decisions, and in The Committed-Artifact Chain spec.md is generated from it. It is the PRD's successor in a document-chain workflow, not a rationale record in a no-PRD one. The homes that qualify are the post-hoc ones: the Codex decision log in a completed plan, the closed issue, and an ADR.

For Carey's method the record costs almost nothing, because the rationale already exists as an artifact. The recorded why-not-what conversation is the why, transcribed (Prototype Over PRD). The persistence page notes the transcript is discarded after handing off. The read-time home is to commit that transcript plus one line naming the chosen variation and why it won, beside the prototype, with no authority over what gets built next. This is the content-layer / presentation-layer split from The HTML Artifact Lifecycle: Where Plan History Lives, and When Disposable Becomes Durable applied to prototypes. Decisions that must persist go into versionable text, and the rich artifact stays disposable. The prototype shows what, and the committed transcript keeps why.

Verdict: settled as posed. A durable read-time home exists and does not reintroduce the PRD: the dated decision record. It keeps the PRD's rationale job and drops its specification job. What decides the PRD question is authority, not persistence.

Answer 3 (partial): the carve-out shrinks, and the keep-current half has mechanisms but no measurement#

What can't live in the codebase: less than Fung thought. Code as Source of Truth names three things: org strategy, the why, and cross-team context. Answers 1–2 remove the why. The Codex team keeps decision logs in the repo, and a dated record has no drift problem to escape. That leaves two defensible residues, each with a source:

Records whose authority lives elsewhere. These are artifacts in Jira, ServiceNow, a regulated requirements tool or Figma that are "hard to displace because auditors and regulators already accept them and other teams depend on them" (The Committed-Artifact Chain's legacy-source-of-truth sidebar). The playbook's per-artifact rule makes the legacy system authoritative and demotes the markdown to a working copy.
Coordination context for people who weren't in the room. Playbook Boundary Conditions: the Devil's-Advocate Substrate and the Prototype's Edge finds the document survives where no artifact's surface covers the risk. One such case is cross-team coordination: "a document is still the medium that travels to teams who weren't there." Nothing stops such a document from sitting in some repo. But it cannot live in this codebase's change loop, because the other team's work is not in it.

Org strategy is not covered by any source. No page in the vault describes where strategy is recorded or how it is kept current in an AI-native org. Tacit knowledge that nobody has written down is the page's other open question, left #oq/source.

Keeping the slice current: mechanisms, all unmeasured.

Mechanism	Covers	Evidence
Regenerate whatever is derivable from code in CI (Factory AutoWiki, "correct with infrastructure, and not with discipline")	derived docs, not the out-of-repo slice	`practitioner-opinion` survey (Code as Source of Truth, LLM-as-Compiler Knowledge Base)
Recurring doc-gardening agent plus CI linters that "validate that the knowledge base is up to date"	in-repo docs	first-party account, no drift rate reported (Harness engineering: leveraging Codex in an agent-first world; the practice is not yet carried into Agent Harness Engineering)
Same-session write-back to the authoritative legacy record through an MCP connector	the out-of-repo slice	prescription only, `vendor-claim` (The Committed-Artifact Chain)
Linkage (record ID in the artifact, commit SHA in the record)	both, at the stated cost of two sources of truth	prescription only
Supersession rather than maintenance	dated rationale	falls out of Answer 1: history needs closing, not updating

The one measurement nearby cuts both ways. Agents change documentation in 41.5% of 33,097 agentic PRs, but when code and docs land in different commits, code comes first in 82.5% (Agent Documentation Behavior). In-loop docs do get touched, and they trail. Nothing in the corpus measures drift for the out-of-repo slice, which is the slice the question is about.

Verdict: partial. The "what" half now has a sharper answer: the why moves into the repo, and the residue is external-authority records, cross-team coordination context and tacit knowledge. The "keep it current" half has named mechanisms with no measurement behind them, and org strategy has no source. Synthesis over existing pages is exhausted here. Settling the rest needs an account of drift in an externally-authoritative record under agent write-back, which is a retag to #oq/source.

Evidence tier and what would overturn this#

Everything load-bearing is vendor-claim (Anthropic's playbook, the Codex team's account, the Genkit tutorial) or practitioner-opinion (Pocock, Carey, Fung, the mem0 survey). The only empirical input is Gao & Chen, which shows the ADR genre is read but not that reading changes decisions. Answers 1 and 2 are conceptual results. They settle where rationale can live and why that home neither stales nor becomes a PRD, using the corpus's own definitions of staleness and authority. They make no outcome claim that teams keeping decision logs make better later decisions.

What would reopen them:

A report of decision records going stale in the harmful sense, for example an agent or engineer misled by an un-superseded decision log. That would show rationale does carry implicit present-tense claims, such as "constraint X still holds", which drift with the code. The mitigation would then be recording the constraints behind a decision as checkable invariants, the Martin move on Is Persistence the Line Between Prompting and Spec-Driven Development?.
Evidence that decision logs are write-only: a trace study like Gao & Chen's showing committed decision records are essentially never consulted at decision time. They would then survive in storage and still fail the "for future readers" clause.

Connections#

Where Does the Why Live?: the parent synthesis. It settled the authoring-time half, and this page supplies the read-time home that page found missing.
Is Persistence the Line Between Prompting and Spec-Driven Development?: supplies both criteria used here. Staleness is a read-back harm, and a spec is defined by authority.
The PRD-Replacement Spectrum at AI-Native Speed: the source of the three PRD jobs. This page answers that spectrum's first unsolved debt (orphaned rationale) for the read-time case.
Playbook Boundary Conditions: the Devil's-Advocate Substrate and the Prototype's Edge: its cross-team-coordination residue is one of the two things that still can't live in the codebase.
The HTML Artifact Lifecycle: Where Plan History Lives, and When Disposable Becomes Durable: the content-vs-presentation split, applied to prototype plus committed transcript.