architecture

name

architecture

description

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.

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 docs/knowledge/glossary.md when load-bearing terms surface mid-interview — additive to ADR creation, never a gate on it.

Critical Rules

The Bar

ADRs are reserved for architecturally significant decisions — those affecting:

• Structure (system boundaries, modules, layering)
• Quality attributes (performance, security, reliability, scalability)
• 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:

1. Architectural significance — does it affect structure, quality attributes, dependencies, interfaces, or construction techniques?
2. 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
3. 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)	ARCHITECTURE.md / VISION.md (mutable, reflect-revisable)
Workflow convention, skill-specific lore	Owning skill's SKILL.md or references
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.

Five statuses: Proposed | Accepted | Rejected | Deprecated | Superseded.

Revising a record (the default evolution path):

• 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.
• Cosmetic edits (typos, broken links) don't bump revised:.

Frontmatter schema:

---
id: ADR-NNN
title: "..."
status: Proposed | Accepted | Rejected | Deprecated | Superseded
date: YYYY-MM-DD            # creation / proposal
revised: 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 Rejected
deprecated_date: YYYY-MM-DD # required iff status is Deprecated
supersedes: ADR-NNN         # optional — points back to the ADR this replaces
superseded_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
• Follow the shared interview protocol in templates/grilling.md
• 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
• ADR created using template at templates/adr.md
• ARCHITECTURE.md updated with new constraints and ADR reference
• ADR number assigned sequentially (ls docs/decisions/ADR-*.md for next number)
• Council convened if decision affects multiple domains
• Glossary read at interview start; any load-bearing term surfaced was offered for stabilize or upsert

Quick Reference

Routing Cheat Sheet

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)	ARCHITECTURE.md / VISION.md (mutable, reflect-revisable)
Workflow convention, skill-specific lore	Owning skill's SKILL.md or references
Local choice, single-PR scope, no consequence to divergence	Log a decision(scope) entry to the project journal + code comment if needed

ADR Numbering

ls docs/decisions/ADR-*.md 2>/dev/null | \
  grep -oE 'ADR-[0-9]+' | sort -t- -k2 -n | tail -1 | awk -F- '{print $2 + 1}'

Start with ADR-001 if none exist.

Council Triggers

Convene when: multiple domains affected, conflicting team opinions, high reversal cost, novel problem, or user requests deliberation.

Evaluation Criteria

For each option: alignment with VISION/ARCHITECTURE, complexity added, reversibility, team capability, maintenance cost.

Glossary Mutation Policy

This skill stabilizes terms — promote a previously-proposed candidate, or write a canonical term directly when one emerges mid-interview.

Verb	When
loaf kb glossary list	At interview start (via grilling protocol)
loaf kb glossary check <term>	When a term's status is in question during the interview
loaf kb glossary stabilize <term>	A previously-proposed candidate has firmed up into a load-bearing decision
loaf kb glossary upsert <term> --definition <d> --avoid <list>	A load-bearing term emerges fresh and is canonical from the outset

propose is reserved for upstream skills that resolve ambiguity (e.g., a future shape evolution) — do not call it here.

Topics

Topic	Reference	Use When
ADR Template	templates/adr.md	Creating new architecture decision records
Grilling Protocol	templates/grilling.md	Running the structured interview, including glossary discipline
Council Workflow	council/SKILL.md	Multi-agent deliberation for complex decisions
Documentation	documentation-standards/references/documentation.md	ADR formatting and standards
Canonical ADR sources	https://adr.github.io/	Reference for ADR practice; format hub
AWS ADR Process	AWS prescriptive guidance	"Architecturally significant" framing, separate-design-from-decision principle
Microsoft Well-Architected ADR	Azure docs	"Difficult to reverse" criterion, append-only log discipline
Nygard original	Documenting Architecture Decisions (2011)	Foundational article; supersession lifecycle
Architecturally Significant Requirements	Wikipedia	ASR test — measurable effect on architecture