docs: record each explanation once, in the venue that owns it

[thodson-usgs]

Why

Rationale accumulated in docstrings alongside the ADRs that already owned it, because adding a paragraph where the reader is standing is easier than citing a record they would have to open.

An audit of dataretrieval/ found ~500 lines restating decisions ADRs 0003–0011 already state:

• configuration.py's module docstring re-derived ADRs 0009/0010/0011 in 65 lines — while citing them three times.
• The no-progress budget was argued from first principles in five places across transport/retry.py, transport/liveness.py, and transport/fanout.py.
• Which failures may be retried was enumerated independently in ADR 0004, ADR 0006, and the architecture overview.

This is a correctness problem rather than a tidiness one. Every copy is a place the rule can be updated without the others, and two had already gone stale — an overview paragraph describing concurrency caps a later ADR removed, and an ADR clause describing a credential rejection the code deliberately no longer performs. A reader has no way to tell which copy is current.

What ADR 0000 decides

Each explanation is recorded once, in the venue that owns that kind of knowledge:

Kind	Venue
The contract — numpydoc Parameters, Returns, Raises, Examples	docstring
Why these lines, when a name cannot carry it	1–2 line comment
Benchmarks, symptoms, what the code used to do	commit message
A decision constraining code outside the file stating it	ADR, cited by number
A term with package-wide meaning	CONTEXT.md

Three rules follow: cite rather than restate, write from the reader's position, and never edit an accepted record to reverse its meaning.

The middle rule was added after review. The venue rules answer where an explanation goes; nothing in them asked who it reads for, and review of this PR found eleven places where correctly-placed prose was still unreadable from outside the author's head. One of them broke this record's own history rule — ADR 0012 inventoried the four deprecation spellings module by module — which means the single review question this record shipped with was not enough. Compliance now asks a second: could a reader who has not opened the cited record follow this sentence?

Public getter docstrings are explicitly out of scope. They hold 55% of the package's docstring lines at 2.5 lines of prose per line of code, and that is the deliverable — the policy says so in as many words, so this cannot be read as licence to trim them.

What changed

• 26 decisions the code was carrying land as clauses in the records that own their subject (0004, 0006, 0007, 0008, 0009, 0011). New ADR 0012 records the deprecation policy, which ADR 0005 covered only for legacy NWIS while four hand-rolled shims accumulated.
• 36 sites across 29 files drop the argument and cite the record — −189 lines. Each keeps the sentence saying what the code does. No numpydoc section was touched and no code changed.
• Three stale ADR statements marked: ADR 0004's resume clause (superseded by 0008 without a backlink), the overview's separate concurrency caps (MAX_CONCURRENT_REQUESTS is gone), and ADR 0009's claim that the **queryables path refuses session, which credentials.py:114 deliberately does not.
• CONTEXT.md gains Dialect, Single-shot adapter, Stall timeout, Fitness function — terms the ADRs used as if defined — and loses two self-contradictions. The largest fix is facade vs adapter: the glossary reserves "facade" for a re-export with no logic of its own, while the overview titled the public surface "facades" and then described nwdc as one that "builds CSV requests".

Enforcement

test_adr_references_resolve_to_a_record asserts every ADR NNNN citation resolves to a record, across every venue ADR 0000 names — package, docs/, CONTEXT.md, CONTRIBUTING.md, AGENTS.md. A renumbered record fails the suite instead of leaving a dead pointer. It caught one bad citation in this PR's own diff.

Whether a given paragraph should have been a citation stays a review judgement. ADR 0000 argues against a proxy metric explicitly: a prose-volume ratio would push contributors to delete parameter documentation to move a number.

Review notes

• Amended records say so in Status. Review asked whether these edits should be addenda. They were — Notes held the log — but at the bottom, so a reader met the amended Decision text first and the fact of amendment last. Status on each amended record now says it was amended and points at Notes.
• Amended records say what changed. Each notes in Notes what was added after acceptance, and where Decision text was corrected rather than added to — ADR 0006's retry scope was widened from "gateway 5xx", which was never true of a fanned-out call. No decision is reversed.
• This PR was reviewed against its own policy and was breaking it in five places: the semaphore rule went from four copies to five, ADRs 0006 and 0009 each restated the other's credential rules, and four records claimed "the rest is unchanged" while their Decision text had been edited. All fixed before squashing.
• Removed history is in the commit message, per the policy — the four-spellings deprecation story, the base_url was-once-optional story, and the _configuration_core.py benchmarks.

Conflict with #388

Both branches amend ADR 0006 and both add a Notes section at the end, so they will conflict. It is a straightforward both-added conflict; land #388 first, since it is further along.

Verification

1130 passed, mypy --strict clean over 60 files, ruff / xenon / complexipy / import-linter all green, every ADR parses clean as RST.

🤖 Generated with Claude Code

[ehinman]

Mostly questions about what the text says and whether it makes sense to add an ADR0000 after ADRs 0001-11 have already been written. Does it make sense to edit the text of an old ADR, or add to it as an addendum? Seemed silly to read through editorial changes to past "Decisions".

[ehinman]

No idea what any of this means.

[thodson-usgs]

Fair — the paragraph reconciled the four sources here against ADR 0011's seven rungs, which is unreadable without 0011 open. It now says the two list the same order, that 0011 is the finer grain, and that an adapter default arrives as the default argument rather than being a fifth source.

[ehinman]

Are these examples needed?

[thodson-usgs]

Trimmed. The three bullets fold into one sentence in the paragraph above — their file-by-file detail belonged to the audit, not to the decision.

[ehinman]

Can we not use "facade"? That's a very AI-y word.

[thodson-usgs]

Leaving this one, with the reasoning: "facade" is the Gang of Four pattern name rather than an AI coinage, CONTEXT.md defines it as a re-export with no logic of its own, ADR 0007 is titled with it, and three architecture tests are named for it. Renaming it is a vocabulary change across the ADR set, the glossary, AGENTS.md, and the tests — worth its own PR if you want it. Say the word and I will open one.

[ehinman]

Fair enough. And I see it defined in the CONTEXT.md In another PR, can we link to the CONTEXT.md in a few more places? Like in the README? This is really helpful for people digging a little deeper into the architecture who are not familiar with the jargon.

[thodson-usgs]

I recommend something like README -> CONTRIBUTING -> CONTEXT, etc. for humans, and AGENTS.md -> CONTEXT, etc. for bots

[thodson-usgs]

@ehinman, thanks for the review. The idea of AD000 was that it will become a general ADR for documentation that we can reuse across projects. That's the longerterm goal at least. When to create a new ADR versus amend an old one is also TBD. The ADR practice seems to be useful, but we need to adapt it for agents that are less human and more like the guy in Memento.

[ehinman]

This is confusing because you got rid of source in a lot of places and replaced it with tier and don't define tier anywhere.

[thodson-usgs]

yeah, there's still some glossary drift. I'm hunting for the bug in the agent design, rather than chasing each instance.

[thodson-usgs]

Correct, and it predates this PR — "it does not replace the package-wide tier" was already in CONTEXT.md before this record was written. Recording each explanation once made the gap visible rather than creating it.

Fixing the one word would have left the reason it got there, and this is the third review in a row to land on the same seam, so #405 addresses the seam: the glossary holds two kinds of term. Ones we invented (chunk, page, source) appear in no USGS API and take one spelling everywhere. Ones the services own (monitoring location, collection) are spelled four different ways upstream — site_no, Station, monitoring_location_id — so the glossary fixes one word for prose while each adapter keeps its own service`'s spelling in its parameters.

That gives your question an answer that does not depend on who reviews: in nwis a docstring may say site; in transport it may not.

[thodson-usgs]

One correction since: swapping in source there was still the wrong axis. Package-wide vs adapter is what ADR 0010 calls a tier — its own word for what the glossary now defines as scope — while a source is block/environment/file/default. The sentence now names neither axis ("leaving that value standing for every other adapter"), and #405 defines Scope and the precedence ladder so source, scope, and rung each mean one thing.