Problem
AI makes drafting an ADR very cheap. That removes useful mechanical work, but it
also removes a natural friction that previously discouraged recording minor or
short-lived implementation details as architecture decisions.
The current ADR skill starts by inspecting context and drafting an ADR. It does
not first decide whether an ADR is the proportionate artifact.
This can produce a formally excellent but increasingly ceremonial architecture
record.
Goal
Add a proportionality gate before the ADR workflow starts.
An ADR should record a decision with durable architectural significance, not
merely an unusual configuration line or implementation detail.
Decision test
Before creating an ADR, ask:
Without this record, would a later contributor probably make a materially
different decision or miss an important assumption?
An ADR is normally justified when one or more of these apply:
- reversing the decision would be costly;
- it constrains multiple future changes;
- it materially affects system boundaries, contracts, quality goals, risks,
deployment or operations;
- it establishes a cross-cutting architectural rule;
- the rejected alternative is plausible enough that the discussion is likely to
recur.
If none applies, prefer the smallest durable record that fits:
- code comment for a surprising implementation detail;
- automated test for required behaviour;
CONTRIBUTING.md for contributor workflow;
- issue or commit message for local change reasoning;
- existing architecture prose when no standalone decision is needed.
Scope
- Add the normative proportionality rule to
general-semantic-contracts.md, under Documenting Decisions.
- Add an
ADR eligibility step before impact analysis in
skills/adr/SKILL.md.
- Allow the skill to return a justified
No ADR recommended result with the
smaller documentation target.
- Update
skills/references/adr-writing-guide.md if it currently describes ADR
selection criteria.
- Do not add a mandatory section to
templates/adr.adoc; the check belongs to
the workflow, not to every rendered ADR.
AI responsibility
AI-generated ADRs remain proposed and reviewed: false. Cheap generation is
not evidence that a decision is ADR-worthy. Only human review may accept both the
decision and the choice to preserve it as an ADR.
Acceptance criteria
- The ADR skill checks proportionality before drafting.
- A configuration-only example results in
No ADR recommended and proposes a
smaller record.
- A cross-cutting decision affecting quality goals and future changes results in
a proposed ADR.
- The general contract contains one canonical rule; the skill references and
applies it without duplicating the full guidance.
- Existing ADR templates and metadata remain backwards compatible.
Origin
Found while validating the toolkit in
dieterbaier/budget: the toolkit made
high-quality ADR creation so inexpensive that artifact proportionality became an
explicit governance concern.
Problem
AI makes drafting an ADR very cheap. That removes useful mechanical work, but it
also removes a natural friction that previously discouraged recording minor or
short-lived implementation details as architecture decisions.
The current ADR skill starts by inspecting context and drafting an ADR. It does
not first decide whether an ADR is the proportionate artifact.
This can produce a formally excellent but increasingly ceremonial architecture
record.
Goal
Add a proportionality gate before the ADR workflow starts.
An ADR should record a decision with durable architectural significance, not
merely an unusual configuration line or implementation detail.
Decision test
Before creating an ADR, ask:
An ADR is normally justified when one or more of these apply:
deployment or operations;
recur.
If none applies, prefer the smallest durable record that fits:
CONTRIBUTING.mdfor contributor workflow;Scope
general-semantic-contracts.md, underDocumenting Decisions.ADR eligibilitystep before impact analysis inskills/adr/SKILL.md.No ADR recommendedresult with thesmaller documentation target.
skills/references/adr-writing-guide.mdif it currently describes ADRselection criteria.
templates/adr.adoc; the check belongs tothe workflow, not to every rendered ADR.
AI responsibility
AI-generated ADRs remain
proposedandreviewed: false. Cheap generation isnot evidence that a decision is ADR-worthy. Only human review may accept both the
decision and the choice to preserve it as an ADR.
Acceptance criteria
No ADR recommendedand proposes asmaller record.
a proposed ADR.
applies it without duplicating the full guidance.
Origin
Found while validating the toolkit in
dieterbaier/budget: the toolkit madehigh-quality ADR creation so inexpensive that artifact proportionality became an
explicit governance concern.