bostonaholic Documenting Decisions
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
# NNNN. Decision Title
## Status
Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-title.md)
## Context
<Objective facts: problem, technical/business constraints, team capability, and timeline.>
## Decision
<Active-voice decision: “We will…”, never “It was decided that…”.>
## Consequences
<What becomes easier and harder; include positive and negative trade-offs.>
File Convention
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 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.
Call the Skill tool with decision-making when a Proposed ADR still has two or
more viable options. Do not reopen an Accepted decision.
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.
Status rules
- 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 rules
- 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.