| name | architecture-decision |
| description | Record architecture decisions as ADRs — compare options, document trade-offs, and track rationale. Trigger on /architecture-decision, or when choosing libraries, designing modules, splitting systems, or making significant technical decisions. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob, Bash, Edit |
Architecture Decision
Record significant technical decisions as ADRs (Architecture Decision Records). Keeps rationale traceable and prevents repeating the same debates.
Workflow
1. Context
- What is the problem or motivation?
- What constraints exist? (time, team size, budget, compliance, runtime)
- What is the current architecture and why isn't it sufficient?
2. Options
- List 2-4 realistic options (not every possible choice).
- For each option: pros, cons, risks, key trade-offs.
- Research real-world usage of each option.
- Consider: maintenance burden, learning curve, ecosystem maturity.
3. Decision
- Which option was chosen and why.
- What was rejected and why (important for future reference).
- Who was involved in the decision.
4. Consequences
- What becomes easier? What becomes harder?
- What must the team learn or adopt?
- What is the migration path from the current state?
- What follow-up decisions are now on the critical path?
5. Write ADR
Store in docs/adr/<number>-<title>.md using template:
# ADR-<number>: <title>
**Status**: [proposed | accepted | deprecated | superseded]
**Date**: YYYY-MM-DD
## Context
...
## Options
- Option A: ...
- Option B: ...
## Decision
Chosen: Option A because ...
## Consequences
...
Rules
- Keep ADR short — one page or less. Detailed analysis goes in a linked doc.
- Do not create ADRs for trivial decisions (package choice, minor config).
- Status must be explicit (proposed/accepted/deprecated/superseded).
- If a decision is reversed, update the old ADR status and create a new one.
Experience Log
This skill learns from experience. Mechanism:
- Read
.claude/experience/'"$s"'.md at skill start to benefit from past lessons.
- Write to
.claude/experience/'"$s"'.md after use if you learned something new.
- Format:
YYYY-MM-DD: <lesson> — one line per entry.
- Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.
