adr-writer
ADR Writer generates architecture decision records (ADR-NNNN.md files) from context, considered alternatives, and selected solutions, preserving design rationale across team transitions. Use this skill when documenting non-trivial architectural choices, reverse-documenting decisions that should have been recorded, or preparing for design reviews by capturing the problem statement, alternatives evaluated, chosen approach, and consequences.
git clone --depth 1 https://github.com/oxbshw/LLM-Agents-Ecosystem-Handbook /tmp/adr-writer && cp -r /tmp/adr-writer/skills/catalog/adr-writer ~/.claude/skills/adr-writerSKILL.md
# 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 fabricateUse when reviewing a proposed REST or GraphQL API change before merge — checks contract clarity, backwards compatibility, errors, pagination, auth, and naming.
Use when first encountering a new dataset — produces a structured profile (schema, missingness, distributions, outliers, gotchas) before any analysis.
Use after an incident is resolved — drafts a blameless postmortem from timeline notes, alerts, and chat threads.
Use when opening a PR — produces a clean PR description (what / why / how to verify / risks) from a branch diff against base.
Use when planning the next sprint — turns ticket intake + team capacity into a planned sprint with explicit non-goals.
Use after a session to promote useful episodic notes from logs/episodic/ into distilled, dated entries in MEMORY.md and memory/semantic/.
Use before connecting a new MCP server to your agent — produces a structured security review covering source, permissions, tools, network, and approvals.