---
name: architecture-decision-records
description: >-
  Documents architectural decisions with context, alternatives, and consequences.
  Use when a significant technical choice is made (database, framework, pattern),
  when onboarding needs decision history, or when revisiting a past decision.
  NOT for task tracking, meeting notes, or code comments.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Identity & Scope

**Executor:** either
**Model tier:** sonnet
**Scope:** Project documentation directories, architecture docs, existing ADRs, source code.
**Off-limits:** Production code changes, deployment actions, deleting existing ADRs.

### Hard Rules
- No credentials in output or git — ever
- No spending money or publishing without explicit user approval
- No deleting files — archive first, 48hr hold
- Report completion to boss via structured output

## Essential Principles

1. **Write at decision time** — Capture context while fresh. Guards against: stale post-hoc rationalizations.
2. **Document rejected alternatives** — Future readers need to know what was considered. Guards against: re-litigating settled decisions.
3. **One ADR, one decision** — Keep each to one page. Guards against: bloated documents burying the decision.
4. **Never delete, only supersede** — Mark old ADRs as superseded. Guards against: losing institutional history.

## When to Use
- Team picks a database, framework, or architecture pattern
- Someone asks "why did we choose X?" and no record exists
- New team member onboarding needs architectural context
- Revisiting a past decision — need original reasoning
- Design review surfaces a trade-off worth recording

## When NOT to Use
- Bug/feature tracking — use an issue tracker instead
- Meeting minutes — use a notes template instead
- API contracts — use OpenAPI instead
- Operational incidents — use incident-response instead

## Rationalizations to Reject

| Shortcut | Why it's wrong |
|----------|----------------|
| "Decision is obvious, no alternatives needed" | Every decision has alternatives. Omitting them forces re-evaluation later. |
| "I'll fill in consequences later" | Consequences fade fastest from memory. Write them now. |
| "Too small for an ADR" | If someone might ask "why?" in 3 months, write it. |
| "I'll update the old ADR" | Never mutate. Supersede with a new ADR. |

## Workflow

### Phase 1: Discovery
**Entry:** An architectural decision has been identified.
**Actions:**
1. Search for existing ADR directories and determine numbering sequence.
2. Identify the decision context from the request, code, or conversation.
3. List alternatives considered (minimum 2 including the chosen option).
**Exit:** Decision context, alternatives, and next ADR number known.

### Phase 2: Draft
**Entry:** Phase 1 complete.
**Actions:**
1. Create ADR file: `ADR-NNN-kebab-case-title.md`.
2. Write all sections: Status, Context (2-3 paragraphs), Decision, Alternatives (pros/cons/rejection reason each), Consequences (positive/negative/risks), Review Date (default 6 months).
**Exit:** Complete ADR with all sections populated.

### Phase 3: Cross-Reference
**Entry:** Phase 2 complete.
**Actions:**
1. Update any superseded ADR's status with forward reference.
2. Verify no ADR number conflicts exist.
**Exit:** All cross-references consistent.

### Phase 4: Verify
**Entry:** All prior phases complete.
**Actions:**
1. Confirm all required sections present: Status, Context, Decision, Alternatives, Consequences, Review Date.
2. Confirm at least 2 alternatives with pros/cons documented.
3. Confirm no placeholder text remains.
**Exit:** All checks pass — report results to boss/user.

## Output Format

```json
{
  "skill": "architecture-decision-records",
  "status": "completed",
  "worker": "worker-012",
  "summary": "Created ADR-007: Use PostgreSQL over MongoDB for user data persistence",
  "findings": [
    {"item": "ADR-007-use-postgresql-for-user-data.md", "severity": "info", "detail": "3 alternatives evaluated. Supersedes ADR-003."}
  ],
  "errors": [],
  "elapsed_seconds": 34.7
}
```

**Bad example:** `{"summary": "Created an ADR", "findings": []}` — No detail on which ADR, what decision, or what alternatives. Boss cannot verify work.

## Escalation Triggers

STOP and report to boss when:
- The decision involves spending money
- You cannot determine what decision was made from available context
- An existing ADR contradicts the new decision without requested supersession
- You've failed the same step 3 times

Report as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`

## Success Criteria

- [ ] ADR file exists with correct sequential numbering
- [ ] All 6 sections present (Status, Context, Decision, Alternatives, Consequences, Review Date)
- [ ] At least 2 alternatives with pros, cons, and rejection rationale
- [ ] No placeholder text remains
- [ ] Any superseded ADRs updated
- [ ] Output matches JSON format above
