# Decision Record

> Use when capturing a significant technical or product decision. Produces a short architecture-decision-record (ADR) that records the context and the alternatives, so future readers understand why, not just what.

- Skill: `dkenge123-oss/decision-record` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkenge123-oss/decision-record`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkenge123-oss/decision-record/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkenge123-oss (https://skillmd.com/u/dkenge123-oss)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkenge123-oss/decision-record

---


# Decision Record

The most expensive thing to lose is *why* a decision was made. Six months on, the code shows what you chose; only a record shows what you rejected and the reason.

## Protocol

1. **Capture the decision at the moment it's made**, while the context and the discarded options are still fresh. A record written a month later is a reconstruction, and it will quietly omit the alternatives that felt obvious at the time.
2. **State the context and forces first.** What situation required a decision? What constraints, deadlines, and tradeoffs were in play? A reader who understands the forces can judge whether the decision still holds when the forces change.
3. **Record the alternatives you seriously considered**, each with why it lost. This is the highest-value part. "We chose Postgres" tells a future reader nothing; "we chose Postgres over DynamoDB because our access patterns are relational and we needed ad-hoc queries" tells them exactly when to revisit.
4. **State the decision and its consequences plainly.** What you are doing, and what this commits you to — the good (what it buys you) and the bad (what it costs, what becomes harder). Honest consequences make the record trustworthy.
5. **Keep it short and immutable.** One page. When a decision is later reversed, do not edit the old record — write a new one that supersedes it and link them. The chain of superseded records is the real history.

## Template

```markdown
# ADR-NNN: <short title>

Status: proposed | accepted | superseded by ADR-MMM
Date: <YYYY-MM-DD>

## Context
<the situation and forces that require a decision>

## Decision
<what we are doing>

## Alternatives considered
- <option>: <why it lost>

## Consequences
<what this makes easier, and what it makes harder>
```

## Never

- Never record only the choice and omit the alternatives; the rejected options are the point.
- Never edit an accepted record to reflect a new decision; supersede it instead.
- Never write a decision record for a trivial, easily-reversed choice. Reserve them for decisions that are costly to undo.

## Done means

A future reader who was not in the room understands the situation, the options, the choice, and its costs well enough to decide whether the decision still applies.