architecture-decision

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.