oxbshw ADR Writer
When to use
- A non-trivial architecture decision was just made
- Reverse-documenting a decision that wasn't recorded but should have been
- Preparing for a design review
When NOT to use
- Trivial choices (naming, formatting)
- Operational runbooks (those go to
runbooks/) - Product decisions without architectural impact
Inputs
| Name | Type | Required | Notes |
|---|---|---|---|
context |
string | yes | The problem being solved, in 2–4 sentences |
options |
list | yes | Alternatives considered |
decision |
string | yes | Chosen path |
number |
int | no | If omitted, finds next ADR number from memory/decisions/ |
Outputs
A file at memory/decisions/ADR-NNNN-<slug>.md matching the ADR template.
Workflow
- Find the next ADR number (or use
numberinput) - Slugify the decision's main subject
- Fill the template:
- Context, Decision, Alternatives, Consequences (positive + negative)
- Status:
accepted(default),proposed,superseded by ADR-XXXX
- Write to
memory/decisions/ADR-NNNN-<slug>.md - Add a one-line entry to
MEMORY.md#decisions
References
Success criteria
- Each alternative has a one-line "why not"
- Consequences include at least one negative
- File name matches
ADR-\d{4}-[a-z0-9-]+\.md
Failure modes
- Decision is actually a bundle of decisions → split into multiple ADRs
- Context is unclear → ask user for clarification, don't fabricate