Creates Architecture Decision Records for architecturally significant decisions — choices that affect the system's structure, key quality attributes, dependencies, interfaces, or construction techniques, or that are difficult to reverse. Captures the rationale for a single such choice and its alternatives so future debate has the why preserved. Not for development patterns or implementation evidence (use shape for SPECs), guiding principles (update ARCHITECTURE.md or VISION.md), workflow conventions (document in the owning skill), or local choices changeable in a single PR (log a `decision(scope)` entry to the project journal instead). ADRs are living records — when a decision evolves, revise the record in place with a dated revision note; supersession is reserved for topic splits and recategorization.
Creates Architecture Decision Records for architecturally significant decisions — choices that affect the system's structure, key quality attributes, dependencies, interfaces, or construction techniques, or that are difficult to reverse. Captures the rationale for a single such choice and its alternatives so future debate has the why preserved. Not for development patterns or implementation evidence (use shape for SPECs), guiding principles (update ARCHITECTURE.md or VISION.md), workflow conventions (document in the owning skill), or local choices changeable in a single PR (log a `decision(scope)` entry to the project journal instead). ADRs are living records — when a decision evolves, revise the record in place with a dated revision note; supersession is reserved for topic splits and recategorization.
subtask
false
version
0.3.1
Architecture
Contents
Critical Rules
Verification
Quick Reference
Topics
Guides decision-making for architecturally significant choices through structured interviews, options analysis, and Architecture Decision Records. ADRs are rare yet binding — they record the rationale for choices that shape the system's structure, quality attributes, dependencies, interfaces, or construction techniques, and that the team agrees to honor until explicitly revised or retired. Most technical decisions do not warrant an ADR; the skill routes those to their proper destination (project journal, SPEC, ARCHITECTURE.md, or owning skill) and stops.
Stabilizes canonical vocabulary in when load-bearing terms surface mid-interview — additive to ADR creation, never a gate on it.
docs/knowledge/glossary.md
Critical Rules
The Bar
ADRs are reserved for architecturally significant decisions — those affecting:
Dependencies (external services, libraries with broad reach, runtime/language commitments)
Interfaces (public APIs, contracts between teams, cross-system protocols)
Construction techniques (build system, deployment model, testing strategy at the system level)
…or are difficult to reverse in the project's current state (would require coordination beyond a single PR — schema migration, contract change, multi-skill update, external-tool retraining).
The bar is a disjunction: either canonical-domain effect, or difficulty of reversal, satisfies it (Microsoft Well-Architected). The Triage Gate below operationalizes the bar more strictly — (Q1 OR Q2) AND Q3 — to keep ADRs rare and binding.
The bar is constant. The number of decisions clearing it scales with project maturity. Projects still exploring their foundational shape clear the bar rarely — usually only foundational shape commitments (language/runtime/standard adoption, primary architectural shape). Mature projects clear it more often as cost-of-change rises across the codebase. When in doubt while the project is still exploring its foundations, prefer SPEC over ADR — SPECs evolve freely; ADR revisions are dated, deliberate acts. In exploratory projects, foundational commitments typically pass via Q2's "Later" prong — the future-cost is the reason to record the rationale while it's fresh, not the current-cost.
An ADR captures a choice. At least one credible alternative was considered and rejected. Without alternatives, you have a principle, vision, or aspiration — record those in ARCHITECTURE.md or VISION.md instead. The presence of an "Alternatives Considered" section in the ADR template is structural, not optional.
Triage Gate
Before grilling, confirm with the user that the decision passes the gate:
Architectural significance — does it affect structure, quality attributes, dependencies, interfaces, or construction techniques?
Cost of divergence — if the team casually diverged from this, what's the consequence? Either:
Now: multi-PR coordination, security regression, contract or interface break
Later: this is a foundational shape commitment (runtime/language/standard adoption, primary boundary) whose future reversal cost is the reason to record the rationale now
Rationale durability — when this debate returns in 18 months, would the team need the why reconstructed, or is it self-evident from the code?
Gate logic: (Q1 OR Q2) AND Q3 → proceed to grilling and ADR.
Q1 and Q2 form a disjunction (matches Microsoft's bar — either canonical-domain effect or difficulty-of-reversal qualifies). Q3 is required regardless: even an architecturally significant or hard-to-reverse decision doesn't need an ADR if its rationale is self-evident from the code itself. Failing the gate → route per the table below and stop.
Decision shape
Destination
Passes the gate
ADR (docs/decisions/)
Development pattern, direction, implementation evidence
SPEC via shape
Guiding principle, philosophy, operating model (stance, not architectural choice)
Local choice, single-PR scope, no consequence to divergence
Log a decision(scope) entry to the project journal + code comment if needed
Skip ADR When
Decision is a convention or naming preference — no measurable effect on architecture (fails the architectural-significance test)
Decision is a stance, principle, philosophy, or vision — even if alternatives are named, the choice is being made on philosophical or operational grounds rather than architectural ones (specific quality attributes, dependencies, interfaces, or construction techniques). Record in ARCHITECTURE.md or VISION.md (strategic), where principles can evolve via reflect. ADRs are dated, deliberate records reserved for architectural choices.
Decision is workflow lore belonging to a specific skill — document in that skill, not in docs/decisions/
Decision is exploration of alternatives without a chosen direction — that's a SPEC via shape; the ADR comes after if the chosen direction is architecturally significant
Decision can be changed in a single PR with no downstream coordination — log a decision(scope) entry to the project journal and a code comment if needed
Rationale is aesthetic ("looks/feels better", "scans nicer", "more consistent visually") — never an ADR
Lifecycle
ADRs are living records — each one carries the current decision on its topic, revised in place under the same ID. Git history is the archive; the working tree carries only current truth. Evolving a decision does not require a new record: rewriting an existing ADR destroys nothing, because every prior state is one git log away, and it keeps every existing citation of the ID truthful.
Rewrite the record in place — same ID, same file. Update the title if the decision's shape changed.
Date the change: set revised: in frontmatter and append one line to a ## Revisions section (chronological, one line per material change).
Accrete alternatives: the framing being replaced and any newly rejected paths join ## Alternatives Considered — this is the "we already weighed that" memory that stops re-litigation.
---id:ADR-NNNtitle:"..."status:Proposed|Accepted|Rejected|Deprecated|Supersededdate:YYYY-MM-DD# creation / proposalrevised:YYYY-MM-DD# optional — latest material revision (mirrors ## Revisions)accepted_date:YYYY-MM-DD# optional — only if differs from `date`rejected_date:YYYY-MM-DD# required iff status is Rejecteddeprecated_date:YYYY-MM-DD# required iff status is Deprecatedsupersedes:ADR-NNN# optional — points back to the ADR this replacessuperseded_by:ADR-NNN# required iff status is Superseded---
Frontmatter encodes the structured what and when. Context for why belongs in the body (## Revisions / ## Deprecated / ## Rejected). Don't duplicate reason or migrated_to as frontmatter fields — they're prose.
Supersession and deprecation are reserved for structural changes, not evolution:
Supersede when a topic genuinely splits (one record becomes two) or a new record absorbs another's domain — set supersedes: on the new record and superseded_by: on the old one; both stay in docs/decisions/. ## Superseded on the old record is optional; the linkage carries the structural relationship.
Deprecate when a record is recategorized — the underlying choice still holds, but the artifact-classification was wrong (it was actually a principle, convention, or workflow lore). The required## Deprecated section explains why and points to the new home. Nothing was replaced; only the classification changed.
Reject a Proposed record the team explicitly decided against. The required## Rejected section explains why and what was chosen instead (if anything). A Rejected ADR is a record of "we weighed this and chose against it" — useful when the same idea resurfaces. Keep them.
Revision is healthy. The bar for writing an ADR is high; once written, the bar for quietly diverging from it is just as high — divergence means a dated revision (or a supersession on topic split), never drift the record doesn't reflect.
When a record changes, sweep its surfaces. A revision that changes what the decision binds — code paths, docs, skills — names the affected surfaces and the realignment work in its Consequences. (A mechanical covers:-style drift check is future work; until it exists, the sweep is authored.)
Always
Run the Triage Gate before grilling. If the gate fails — (Q1 OR Q2) AND Q3 is not satisfied — route to the destination in the table and stop.
When a decision is architecturally significant but routes elsewhere (SPEC, ARCHITECTURE.md, owning skill), help the user place it in the right destination. The skill's job is correct routing, not just ADR creation.
Read existing VISION.md, ARCHITECTURE.md, and ADRs before proposing changes
Read docs/knowledge/glossary.md at interview start (via loaf kb glossary list); use canonical terms throughout
When fuzzy/drifted language surfaces, challenge inline; if a load-bearing term emerges, offer loaf kb glossary upsert or stabilize
Present multiple options with pros/cons and "fits when" context
Wait for explicit user decision before proceeding with documentation
Log decision to the project journal: loaf journal log "decision(architecture): ADR-NNN adopted for X"
Never
Make architectural decisions without user input
Contradict an existing record without revising it — divergence means a dated revision (or supersession on topic split), never quiet drift
Proceed past the Triage Gate when it fails — i.e., when neither Q1 nor Q2 affirms, or when Q3 fails. ADRs require (Q1 OR Q2) AND Q3.
Create ADRs without user approval, even when the user requests one — if the decision fails the Triage Gate, propose the correct destination and decline the ADR
Use the word "irreversible" — software decisions can always be reversed via revision or supersession; the operative criterion is "difficult to reverse"
ADR-ify aesthetic preferences, naming conventions, workflow lore, or guiding principles — those have other homes (see Skip ADR When)
Revise a record without dating it — every material change sets revised: and appends a ## Revisions line; git history is the archive, the revision note is the reader's signal
Block ADR creation on glossary state — glossary mutations are additive and opt-in
Call loaf kb glossary propose (reserved for upstream ambiguity-resolving skills)
Verification
After work completes, verify:
Triage Gate ran before any grilling; gate passed (Q1 OR Q2) AND Q3 before proceeding
Decision passes the bar: architecturally significant (canonical domains) OR difficult to reverse (cost of divergence)
ADR captures rationale, not exploration (exploration belongs in a SPEC)
If the decision evolved an existing record, the revision is dated (revised: frontmatter + ## Revisions entry) and the replaced framing joined Alternatives Considered; genuine supersession carries supersedes:/superseded_by: linkage
