adr
Captures one decision with its context, rejected options and consequences in a numbered, immutable record.
looks for
- a technology or vendor choice
- a change that is hard to reverse
- a decision made in chat that nobody wrote down
- why is it like this?
outputs
- → {{ADR_DIR}}/NNNN-short-title.md
- → an updated ADR index
SKILL.md
ADR
One decision per file. Short. Written when the decision is made, not months later.
File
{{ADR_DIR}}/NNNN-kebab-title.md, numbered in order, never reused.
Template
# NNNN. <Decision as a short statement>
- **Status:** proposed | accepted | superseded by NNNN | deprecated
- **Date:** YYYY-MM-DD
- **Deciders:** <roles>
## Context
What forces are at play: the problem, constraints, deadlines, what we know and
don't. 3–8 sentences. Link evidence (benchmarks, spikes, incidents).
## Options considered
1. **Option A** — one line. + pros. − cons.
2. **Option B** — …
3. **Do nothing** — always list it.
## Decision
We will … because …
## Consequences
- Good: …
- Bad / accepted cost: …
- Follow-ups: …
## Revisit when
<the signal or date that would reopen this>
Rules
- Accepted ADRs are immutable. To change a decision, write a new ADR that supersedes it and update the old one's status line only.
- Include "do nothing" and at least one real alternative.
- Consequences include the bad ones.
- Keep an index (
{{ADR_DIR}}/README.md) with number, title, status.
Customize for your project
{{ADR_DIR}} (e.g. docs/adr), who signs off, and whether ADRs go through PR review.
pairs with
- skilltrueorfalse
decision-council
Runs five opposing advisor views and a cross-examination, then a chair commits to one call and writes it up.
- an irreversible or costly choice (architecture, pricing, build vs. drop, rewrite)
- "council this", "second opinion", "should we…?"
- a plan everyone already agrees with
Claude · Codex · ChatGPT - personatrueorfalse
tech-lead
Locks contracts and architecture decisions before specialists build, and unblocks them when the design is unclear.
- a change that crosses module or service boundaries
- a new or changed endpoint, event or table
- a proposed new dependency
Claude · Codex · ChatGPT - skilltrueorfalse
package-choice
Runs a dependency decision tree and recommends stdlib, an existing dep, a default pick or a small local function.
- a new entry in package.json / requirements / Cargo.toml
- two libraries that overlap (two date libs, two HTTP clients)
- a heavy package used for one function
Claude · Codex · ChatGPT - personatrueorfalse
docs-scribe
Updates the docs that a change made stale, documenting only what was actually built.
- a new or changed endpoint
- a new table, column or model field
- a new folder or module without a map
Claude · Codex · ChatGPT