AI agent skill · by @oxbshw

Adr Writer

Use when capturing an architecture decision so it survives turnover — produces an ADR-NNNN.md from context, options considered, and the chosen path.

Archived 2026-10-23 · Source updated 2026-06-30 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# 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](../../../templates/ADR.md.template).

## Workflow
1. Find the next ADR number (or use `number` input)
2. Slugify the decision's main subject
3. Fill the template:
   - Context, Decision, Alternatives, Consequences (positive + negative)
   - Status: `accepted` (default), `proposed`, `superseded by ADR-XXXX`
4. Write to `memory/decisions/ADR-NNNN-<slug>.md`
5. Add a one-line entry to `MEMORY.md#decisions`

## References
- [`../../../templates/ADR.md.template`](../../../templates/ADR.md.template)
- [`../../../design_docs/adr_guide.md`](../../../design_docs/adr_guide.md)

## 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