---
name: architecture-decision-recorder
description: Generates a properly structured Architecture Decision Record (ADR) capturing context, options considered, decision, consequences, and links — ready to commit to your /docs folder.
version: 1.0.0
author: VantagePoint Networks
audience: IT Managers, Solution Architects, Engineering Leads, Platform Owners
output_format: Formatted Markdown ADR following Michael Nygard's template, ready to drop into a docs/adr/ folder under version control.
license: MIT
---

# Architecture Decision Recorder

Walks through an architectural decision and produces an ADR — the durable record of "why we built it this way" that future engineers (and you, six months later) will actually thank you for.

## How to use this skill

1. Download this `SKILL.md` file.
2. Place it in `~/.claude/commands/` (macOS / Linux) or `%USERPROFILE%\.claude\commands\` (Windows).
3. Run `/architecture-decision-recorder` in Claude Code. Describe the decision in conversation. The skill will probe for context, alternatives, and consequences. Receive the ADR.

## When to use this

- A meaningful architectural / platform / tooling decision has just been made (or is about to be).
- You're starting a new system and want a clean ADR-0001 baseline.
- A decision is being challenged 18 months later and there's no record of why it was made.
- You're handing over a system and want to leave a trail of decisions, not just code.
- You're standardising the practice across teams and need a template + cadence.

## What you'll get

- **Numbered ADR** following the Michael Nygard format (the most widely adopted).
- **Context** — the situation forcing the decision, with constraints and forces.
- **Options considered** — at least 3, scored against criteria.
- **Decision** — what was chosen, by whom, on what date.
- **Consequences** — what improves, what worsens, what's now harder.
- **Links** — related ADRs (supersedes, related to, depends on).
- **Status field** — Proposed / Accepted / Deprecated / Superseded.
- **Suggested filename** — for direct commit to `docs/adr/`.

## Clarifying questions I will ask you

1. **What's the decision in one sentence?** (The verb matters — "use", "adopt", "replace", "deprecate")
2. **What problem or situation forces the decision now?** (Trigger — incident, growth, deprecation, new requirement)
3. **What constraints frame the choice?** (Budget, timeline, regulatory, skills, existing tech, customer commitments)
4. **What options did you genuinely consider?** (Even ones rejected fast — they belong in the record)
5. **What were the criteria you scored against?** (Cost, complexity, security posture, vendor risk, time-to-deliver, ops burden)
6. **Who participated in the decision?** (Roles, not just names — gives durability if people change)
7. **Who decided?** (The accountable role)
8. **What changes for users / operators / future developers?** (Consequences good and bad)
9. **What is now NOT possible (or much harder) because of this choice?** (The cost of the path taken)
10. **What previous ADRs does this supersede or depend on?**
11. **What revisit triggers should we set?** (e.g. "if vendor X changes pricing model > 20%, revisit")

## Output template

```markdown
# ADR-NNNN: <Short, present-tense title>

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Date:** YYYY-MM-DD
**Decision-maker:** <Role / RACI accountable>
**Participants:** <Roles>
**Tags:** <tag1, tag2 — for grep / filter>

## Context

<2-3 paragraphs. Describe the situation. Include:>
- The forces at play (technical, organisational, regulatory)
- What we know to be true
- What we don't yet know
- Constraints (budget, timeline, skills)
- Existing system(s) this affects

The decision is forced by: <trigger>.

## Decision Drivers (criteria we scored against)

- **<Criterion 1>** — <how we'd measure / why it matters>
- **<Criterion 2>** — <...>
- **<Criterion 3>** — <...>
- **<Criterion 4>** — <...>

## Options Considered

### Option 1 — <Name / approach>
**Summary:** <one paragraph>

| Criterion | Score | Notes |
|---|---|---|
| <Criterion 1> | <1-5 / pass-fail> | <reason> |
| <Criterion 2> | <> | <> |
| <...> | <> | <> |

**Pros**
- <bullet>
- <bullet>

**Cons**
- <bullet>
- <bullet>

### Option 2 — <Name>
<same structure>

### Option 3 — <Name>
<same structure>

(Add as many as were genuinely considered. Don't fabricate "do nothing" if it wasn't seriously on the table.)

## Decision

We will <decision>.

This was selected over the alternatives because:
- <Reason 1, evidence-backed>
- <Reason 2>
- <Reason 3>

The decision was made on YYYY-MM-DD by <decision-maker role>.

## Consequences

### Positive
- <What gets better — capability, posture, cost, speed>
- <Bullet>

### Negative
- <What gets harder, slower, more expensive>
- <The cost of this path — be honest>

### Neutral
- <What changes operationally without being clearly better or worse>

### What this makes harder or impossible
- <Be explicit. Future ADRs may revisit this — they need to know what was traded away.>

## Compliance / Risk Notes

- **Security:** <impact on attack surface, data flow, identity>
- **Compliance:** <impact on ISO / SOC / GDPR / sector regs>
- **Operational risk:** <what breaks if this fails>
- **Vendor risk:** <if a vendor is involved — viability, lock-in, exit cost>

## Implementation Notes

<Brief — implementation belongs in design docs, not ADRs. Include only what materially affects the decision's success.>

- Phased rollout: <yes/no, how>
- Reversibility: High / Medium / Low — <how reversible if we change our mind>
- Skills required: <new skills to learn / hire>
- Estimated cost / effort: <bands, not precision>

## Revisit Triggers

This decision should be re-evaluated if:
- <Specific external trigger — e.g. "vendor pricing model changes by > 20%">
- <Specific internal trigger — e.g. "we exceed 100k events/sec">
- <Specific time trigger — e.g. "annually as part of architecture review">

## Related ADRs

- **Supersedes:** ADR-XXXX <title>
- **Superseded by:** ADR-XXXX <title>  (fill in if/when this is replaced)
- **Related to:** ADR-XXXX <title>
- **Depends on:** ADR-XXXX <title>

## References

- <Vendor docs URL>
- <RFC / standard reference>
- <Internal RFC, design doc, ticket>
- <Comparison reports, benchmarks>

---

**Filename suggestion:** `docs/adr/<NNNN>-<short-slug>.md`
**Author:** <name>
```

## Example invocation

**User:** "/architecture-decision-recorder — we just decided to adopt PostgreSQL as the standard relational database for new services, deprecating MySQL on new projects. Existing MySQL stays."

**What the skill will do:**
1. Probe context — what triggered now? (Likely consolidating skills, vendor support, or feature need.)
2. Surface alternatives that were considered — at minimum: stay on MySQL, move to managed cloud DB (Aurora / Cloud SQL), consider PostgreSQL + a NoSQL alternative for some workloads.
3. Force scoring against criteria (likely: feature set, ops familiarity, cost, ecosystem, vendor lock-in).
4. Capture consequences — explicit "MySQL skills decay over time", "Postgres extension ecosystem unlocks X", "existing tooling needs replacement".
5. Set revisit triggers — e.g. "if a major workload requires MySQL-specific feature unavailable in Postgres".

## Notes for the requester

- **One decision per ADR.** "We adopt PostgreSQL AND containerise all services" = two ADRs. Easier to supersede individually.
- **Number them sequentially**, never reuse numbers, never delete (only mark superseded).
- **The Context section is half the value.** Future-you needs to know not just what was decided but the world it was decided in.
- **List rejected options honestly.** If "do nothing" was an option, score it. Don't fabricate alternatives to make the chosen path look strong.
- **Status discipline matters.** "Proposed" lives until accepted. After acceptance, edits are rare — supersede with a new ADR rather than rewrite history.
- **Store in version control alongside the code** (`docs/adr/` is the convention). PR review of an ADR is part of the decision process, not a formality.
- **Tag for searchability.** Tags like `database`, `cloud`, `security`, `vendor-selection` make the ADR set browsable.
- **"Good" looks like:** an engineer joining the team in 2 years reads this ADR and understands why the system is what it is, without needing to interview anyone who was there.