documenting-decisions · diff
git:20260828.1805950 to git:20260904.5a122b3
15 added, 90 removed. Audit A to A.
---
name: documenting-decisions
- description: Architecture Decision Record format — capturing the context, decision, alternatives considered, and consequences of a significant technical choice. Load when recording an architectural decision or writing an ADR.
+ description: 'Defines ADR structure and lifecycle. Load when recording a consequential architecture decision and its alternatives.'
user-invocable: false
---
# Documenting Decisions
- Architecture Decision Records (ADRs) capture important technical decisions
- with their context, rationale, and consequences. They are the institutional
- memory that explains WHY the codebase looks the way it does.
-
- Write the prose this skill governs at a seventh-grade reading level, in
- STE-flavored mode — short sentences, common words, no unexplained jargon.
- Full methodology: `writing-prose`. Before
- you finalize prose this skill governs, call the Skill tool with
- `writing-prose` and apply its `## Self-lint` checklist.
+ An Architecture Decision Record (ADR) records an important technical choice, its context, alternatives, and consequences. Write at seventh-grade, STE-flavored level; call the Skill tool with `writing-prose` and apply `## Self-lint` before finalizing.
## ADR Format
- Every ADR follows this structure:
-
```markdown
# NNNN. Decision Title
## Status
-
Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-title.md)
## Context
-
- What is the issue that we're seeing that is motivating this decision or change?
- Describe the forces at play — technical constraints, business requirements,
- team capabilities, timeline pressure. Be objective: state facts, not opinions.
+ <Objective facts: problem, technical/business constraints, team capability, and timeline.>
## Decision
-
- What is the change that we're proposing and/or doing? State the decision in
- full sentences, using active voice: "We will..." not "It was decided that..."
+ <Active-voice decision: “We will…”, never “It was decided that…”.>
## Consequences
-
- What becomes easier or more difficult to do because of this change? List both
- positive and negative consequences. Every decision has trade-offs — if you
- cannot identify any negative consequences, you have not thought hard enough.
+ <What becomes easier and harder; include positive and negative trade-offs.>
```
## File Convention
- ADRs live in `docs/decisions/` with zero-padded sequential numbering:
-
- ```
- docs/decisions/
- 0001-use-typescript-for-plugin.md
- 0002-agent-per-phase-architecture.md
- 0003-file-based-state-management.md
- ```
-
- To determine the next number, read the existing files in `docs/decisions/`
- and increment the highest number. If the directory is empty or does not exist,
- start at `0001`.
+ Store ADRs under `docs/decisions/` with zero-padded sequence names: `0001-use-typescript-for-plugin.md`, `0002-agent-per-phase-architecture.md`, `0003-file-based-state-management.md`. Read existing files, increment the highest number, or start at `0001` when absent/empty.
## When to Write an ADR
- Write an ADR when the decision:
-
- - **Chooses between alternatives** — You evaluated multiple options and
- picked one. The rejected alternatives and the reasons for rejection are
- valuable context for future developers who will wonder "why did not we
- just..."
-
- - **Involves important trade-offs** — The decision sacrifices something
- (performance, simplicity, flexibility) to gain something else. Record what
- was traded and why.
-
- - **Breaks an established convention** — Deviating from existing patterns is
- sometimes correct, but the reasoning must be explicit so the deviation is
- not "fixed" back by a future developer who assumes it was a mistake.
-
- - **Introduces a new dependency** — Adding a library, service, or tool creates
- a long-term commitment. Record why this dependency was chosen over
- alternatives and what the exit strategy is.
-
- ## When NOT to Write an ADR
-
- Do not write an ADR when:
-
- - **The choice is obvious** — If there is one clearly correct option and no
- reasonable alternative, an ADR adds bureaucratic overhead without value.
-
- - **Following established patterns** — If the codebase already uses a pattern
- and you are applying it to a new case, no decision was made.
-
- - **Minor implementation details** — Function naming, variable scoping, loop
- structure. These are code-level decisions, not architecture-level.
+ Write one when choosing among alternatives, accepting important trade-offs, breaking an established convention, or adding a long-lived dependency. For dependencies, record why it beat alternatives and the exit strategy.
- - **The decision is trivially reversible** — If the choice can be changed in
- minutes with no downstream impact, it does not need formal documentation.
+ Do not write one for an obvious choice, use of an established pattern, minor implementation details (names, variable scope, loop form), or a choice reversible in minutes without downstream effects.
- ## ADR Statuses
+ ## Status rules
- - **Proposed** — written, not yet accepted; open for discussion.
- - **Accepted** — in effect; the codebase should conform.
- - **Deprecated** — no longer relevant (the system it covers is gone). The ADR
- stays for historical context.
- - **Superseded** — replaced by a newer decision. The ADR must name its
- successor (`Superseded by [0007](0007-new-approach-to-state.md)`), and the
- successor references what it supersedes in its Context section, so the
- decision trail stays walkable in both directions.
+ - **Proposed:** open for discussion. **Accepted:** in effect; code must conform. **Deprecated:** retained after its subject disappears.
+ - **Superseded:** link the successor as `Superseded by [0007](0007-new-approach-to-state.md)`; the successor names the prior ADR in Context so navigation works both ways.
- ## Writing Guidance
+ ## Writing rules
- - **Be specific.** "We chose X because it is better" is not useful. "We chose
- X because it supports concurrent writes without locking, which Y does not"
- is useful.
- - **Name the alternatives.** Every decision implies rejected alternatives.
- List them and say why they were rejected.
- - **Acknowledge uncertainty.** If the decision was made with incomplete
- information, say so. Future readers will know to re-evaluate if new
- information emerges.
- - **Keep it short.** An ADR should be readable in under 5 minutes. If it
- takes longer, you are including implementation details that belong in code
- or comments.
+ - State specific facts and reasons; name rejected alternatives and why.
+ - Record incomplete information so later readers know when to reconsider.
+ - Keep it readable in under 5 minutes; implementation detail belongs in code or comments.