The cost of decisions accepted without understanding

## Spark

Nygard's "Documenting Architecture Decisions" surfaced in Readwise on
2026-07-20 — "if the project accumulates too many decisions accepted without
understanding, then the development team becomes afraid to change anything and
the project collapses under its own weight" — in the same week five repos took
ADR actions.

## Why it could be interesting

The ADR failure mode people describe is the undocumented decision. Nygard's is
the *accumulation*: past some density of decisions nobody can reconstruct, the
response isn't confusion, it's paralysis — you stop changing things. That
reframes ADRs from documentation hygiene into a change-velocity control, which
is a different and more defensible reason to write them. At scale-of-one with
agents proposing most of the decisions, accumulation outruns understanding
faster than it would on a team.

## Open questions

- [ ] Does the accumulation threshold exist at scale-of-one, or is paralysis a team-communication artifact that a solo author never hits?
- [ ] When an agent proposes the decision, who holds the understanding — and is the ADR the transfer mechanism or just the receipt?
- [ ] Relationship to #176 (ADRs you didn't write) and #328 (ADR-first greenfield): one post, or three that need sequencing?
- [ ] Is there evidence in the existing repos — a decision that went unrecorded and later blocked a change?

## Source material

- Readwise highlight, 2026-07-20 — Nygard, Documenting Architecture Decisions: https://read.readwise.io/read/01kxz9ty2xemjj0kh964g5mgnw
- zfs-replicate PR#511 — ADR for the parallel-replication scheduler: https://github.com/alunduil/zfs-replicate/pull/511
- alunduil-chezmoi PR#409 — renumber the per-workflow-CI ADR off a 0002 collision: https://github.com/alunduil/alunduil-chezmoi/pull/409
- partir.qua.world#76 — record the error-handling convention as an ADR: https://github.com/qua-world/partir.qua.world/issues/76
- genshin.dungeon.studio#966 — decide representation strategy for nested resources: https://github.com/dungeon-studio/genshin.dungeon.studio/issues/966
- zellij-claude-pair#27 — Diataxis docs tree with an ADR log: https://github.com/alunduil/zellij-claude-pair/issues/27
- Adjacent existing ideas: #176, #328