Repository navigation
Replies: 5 comments 1 reply
|
I don't think you're holding it wrong so much as the ADR folder is carrying things the skills would put elsewhere. Going by what 1. A lot of them may not clear the ADR bar. An ADR is only offered when all three are true: hard to reverse, surprising without context, and the result of a real trade-off. Titles in your graph like "ADR 0073 — A Card rail is a toolbar", "ADR 0064 — Opening a Card expands it in place" or "ADR 0083 — A Card Title is Title Lines" read like UI behaviour you could change in an afternoon. That can just live in the code. Some others read more like definitions of terms, and those belong in 2. Renames belong in the glossary, not in ADR chains. "ADR 0041 — Graph is the first-public name for Route", "ADR 0085 — Thing and Diagram are the first-public names for Card and Layout" and "ADR 0092 — Reference Thing is the first-public name for Alias" are naming decisions. The glossary format handles those with one entry per canonical term plus an 3. Agents shouldn't be reading all of them. The rule that 4. Compacting. The format already supports
Going forward, the three-part test is the filter. Most of the churn you describe (iterating on the design, renaming core concepts) is exactly what it's meant to keep out of |
|
OKF(Open Knowledge Format ) exist for this kind of problems. Of course there is much more complex solutions but for ADR still simple and good solution would be OKF still. |
|
Building on the scoping and glossary advice above, we tested an offline approach to the mechanical selection problem in Atlas Opsbook. It uses a reviewed catalogue of status, scope and supersession relationships to select current accepted decisions plus global decisions. It preserves the original text, rejects cycles and ambiguous successors, and binds selected text to source hashes. Exceeding the context byte budget produces a failure rather than silent truncation. The reproducible example and guide include a synthetic 150-record trial: python3 examples/decision_context_trial.py
python3 -m unittest discover -s tests -p test_decision_context.py -qThat trial selected two applicable records and detected six deliberate failures: catalogue drift, selected-source drift, a graph cycle outside the requested scope, unspecified scoped status, bundle tampering and budget overflow. All 31 decision-context tests passed when we reran them. The limitation is semantic: this does not decide which ADR is right or automatically consolidate its meaning. Status, scope and supersession still need review. For your case, I would first classify one bounded context, retain the original records, then make the agent's selected context an inspectable derived artifact. The synthetic trial demonstrates the tested selection and integrity behaviour; improved reasoning on a real project remains unmeasured. |
|
FWIW, this is an ADR "snapshot" skill I have been experimenting with |
|
I strongly suggest this research paper on agentic infrastructure in general, that's the one that threw me into the rabbit hole though :) |
Uh oh!
There was an error while loading. Please reload this page.
Salutations 👋
Long-time fan, first-time questioner, love your work.
I have a project that now has ~150 ADRs (and counting).
There has been a TON of churn as I've iterated, including some renames of core domain concepts as the design evolved.
The side effect has been a collection of ADRs that have increasingly complex dependency chains of superseded, refined, obsolete requirements and noise that overloads agent context.
See also:

Has anyone run into this problem?
Am I holding it wrong?
Has anyone implemented an approach to "compacting" or consolidating the project record into a more coherent structure?
ktnxbye
All reactions