| name | decision |
| description | Log an architectural decision (ADR) so the reasoning survives across sessions. Use right after you pick a library, a pattern, or a trade-off. Takes 30 seconds while it's fresh. Prevents "why did we do it this way?" re-debates months later. Also retrieves past decisions with `/decision list` or `/decision <topic>`.
TRIGGER — suggest this skill (even without /decision prefix) when the user: picks between options ("X or Y?", "should we use A vs B", "choosing between"), asks "why did we pick X?", "why are we using Y?", "why did we choose", wants to document a trade-off, mentions "architectural decision", "ADR", "tech choice", accepts a trade-off ("going with X despite the downside of Y"), or **acts on a structural finding from a 🏛 architecture audit** (e.g. splitting a god-module, breaking a dependency cycle) — the *why* of the restructure should outlive the review.
SKIP — for trivial picks with no trade-off (e.g. picking a variable name).
|
| user-invocable | true |
| argument-hint | [title to log new ADR | 'list' | topic to search] |
Log or Retrieve a Decision
ADRs preserve why you chose X over Y. Without them, the next session (or the next person) re-debates it from scratch.
Step 1 — Check the file exists
ls docs/DECISIONS.md 2>/dev/null
If missing: create it with this template:
# Decision Log (ADRs)
> Every architectural / library / pattern / scope decision that will be second-guessed later.
> Newest at top. Never delete — if a decision is reversed, add a new ADR that supersedes the old one.
---
Step 2 — Read the argument
Argument = list
Read docs/DECISIONS.md. Extract every ## ADR-NNN: heading. Output:
ADR log (N total)
Accepted:
- ADR-001: <title> — YYYY-MM-DD
- ADR-003: <title> — YYYY-MM-DD
Superseded:
- ADR-002: <title> — superseded by ADR-005
Argument = a topic (e.g. "auth", "database")
Grep docs/DECISIONS.md for the term. Return matching ADRs with their Decision + Consequences summarised.
Argument = a title (log a new one)
- Find the highest existing ADR number. New one is
ADR-(N+1).
- Ask the user — one terse prompt:
📋 Logging **ADR-NNN: <your title>** at the top of `docs/DECISIONS.md`.
**Tell me, in your own words:**
- 🎯 **Problem:** what forced this?
- ✅ **What you picked:** one sentence.
- 🤔 **What you considered:** 2+ alternatives + why they lost.
- ⚖️ **Trade-off:** what does this cost? what would reverse it?
- 🙋 **Decider(s):**
*Stuck on the format? Say "example" and I'll show one.*
- Write the ADR at the top of
docs/DECISIONS.md (newest first):
## ADR-NNN: <Title>
**Date:** YYYY-MM-DD
**Status:** accepted
**Decider(s):** <name(s)>
### Context
<from user>
### Decision
<from user>
### Alternatives considered
- **<Option A>** (chosen) — <reason>
- **<Option B>** — <why rejected>
- **<Option C>** — <why rejected>
### Consequences
- Positive: <…>
- Trade-off: <…>
- Revisit if: <condition that would make us reconsider>
- If this decision supersedes an older one:
- Add "Supersedes ADR-MMM" to the new ADR.
- Edit the old ADR: change
Status: accepted → Status: superseded by ADR-NNN (YYYY-MM-DD).
- Never delete the old ADR.
Output
📋 **ADR-NNN: <title>** logged at top of `docs/DECISIONS.md` (status: accepted).
👉 **My recommendation:** <one line — usually "keep going" unless this decision blocks something>.
