Key Decision Document (KDD)
A KDD records a significant decision so that, months later, anyone can see
what was decided, why, who agreed, and when to revisit it. It's the broader
sibling of the ADR: an ADR is scoped to system architecture and lives beside the
code, whereas a KDD covers any consequential choice — product, process, tooling,
vendor, organisational, cross-team — that future people will need the reasoning
for.
KDD vs ADR — pick the right one
- Architectural/technical decision (datastore, API contract, system
boundary) → use the adr skill. ADRs are numbered, immutable, in-repo.
- Broader significant decision (which vendor, a team process, a roadmap
trade-off, a tooling standard) → KDD. KDDs record stakeholders/approvers and
a revisit date, because such decisions are often time-bound and owned by
people outside a single codebase.
If you're unsure and the decision is fundamentally about how the system is
built, prefer an ADR.
When to use it
When a decision is expensive to reverse, affects multiple people or teams, sets a
precedent, or will predictably be questioned later ("why are we doing it this
way?"). Skip it for routine, low-impact, or easily reversed choices.
Canonical structure
- Decision Summary — the decision in one or two sentences, up front, so a
reader gets the answer immediately.
- Context / Background — the situation that forced the decision: problem,
constraints, what prompted it now.
- Decision Drivers — the criteria that actually mattered (cost, time-to-
market, risk, team capacity, strategic fit…).
- Options Considered — the serious alternatives, each with its trade-offs
against the drivers. Include "do nothing / status quo" where relevant. At
least two.
- Decision & Rationale — what was chosen and why it beat the alternatives,
tied back to the drivers.
- Stakeholders / Approvers — who was consulted, who decided, and who signed
off (RACI-style if useful). This is what distinguishes a KDD from an ADR.
- Implications & Follow-ups — consequences, new commitments, dependencies,
and the concrete next steps with owners.
- Review / Revisit Date — when this should be re-examined, or the condition
that would reopen it. Decisions made under today's assumptions should have an
expiry.
Quality rubric
A strong KDD:
- Answers first — the decision is stated up top, not buried.
- Shows the work — drivers + ≥2 options with honest trade-offs, not a
single foregone conclusion.
- Names accountability — explicit approvers/stakeholders, not an anonymous
"we decided".
- Justifies over alternatives — explains why the chosen option won.
- Has a revisit trigger — a date or condition for re-examination.
- Is honest about implications — downstream costs and commitments, not just
upside.
Common pitfalls
- Reaching for a KDD when it's really an architectural decision (use an ADR).
- No named approvers — the decision has no accountable owner.
- Listing only the chosen option; no drivers, no alternatives.
- No revisit date — stale decisions silently outlive their assumptions.
- Restating background at length while burying the actual decision.
Naming & storage
- Directory:
docs/decisions/
- Filename:
NNNN-kebab-case-title.md, zero-padded sequence (or date-prefixed if
you prefer chronological ordering).
- Track status:
Proposed → Decided → Revisited / Superseded.
Template
Copy templates/kdd.md and fill it in.
Related
- For architectural/technical decisions, use the adr skill.
- If a KDD requires a deeper design exploration first, write an rfc and link
it from the Context section.
1---2name: kdd3description: Write or improve a Key Decision Document (KDD) — a record of a significant decision that is not purely architectural: product direction, process, tooling, vendor, or cross-team choices. Use when the user wants to capture a key decision, its rationale, the options weighed, and who signed off. For a purely architectural/technical decision, use the adr skill instead.4---56# Key Decision Document (KDD)78A KDD records a **significant decision** so that, months later, anyone can see9what was decided, why, who agreed, and when to revisit it. It's the broader10sibling of the ADR: an ADR is scoped to system architecture and lives beside the11code, whereas a KDD covers any consequential choice — product, process, tooling,12vendor, organisational, cross-team — that future people will need the reasoning13for.1415## KDD vs ADR — pick the right one1617- **Architectural/technical decision** (datastore, API contract, system18 boundary) → use the **adr** skill. ADRs are numbered, immutable, in-repo.19- **Broader significant decision** (which vendor, a team process, a roadmap20 trade-off, a tooling standard) → KDD. KDDs record **stakeholders/approvers** and21 a **revisit date**, because such decisions are often time-bound and owned by22 people outside a single codebase.2324If you're unsure and the decision is fundamentally about how the *system* is25built, prefer an ADR.2627## When to use it2829When a decision is expensive to reverse, affects multiple people or teams, sets a30precedent, or will predictably be questioned later ("why are we doing it this31way?"). Skip it for routine, low-impact, or easily reversed choices.3233## Canonical structure34351. **Decision Summary** — the decision in one or two sentences, up front, so a36 reader gets the answer immediately.372. **Context / Background** — the situation that forced the decision: problem,38 constraints, what prompted it now.393. **Decision Drivers** — the criteria that actually mattered (cost, time-to-40 market, risk, team capacity, strategic fit…).414. **Options Considered** — the serious alternatives, each with its trade-offs42 against the drivers. Include "do nothing / status quo" where relevant. At43 least two.445. **Decision & Rationale** — what was chosen and *why it beat the alternatives*,45 tied back to the drivers.466. **Stakeholders / Approvers** — who was consulted, who decided, and who signed47 off (RACI-style if useful). This is what distinguishes a KDD from an ADR.487. **Implications & Follow-ups** — consequences, new commitments, dependencies,49 and the concrete next steps with owners.508. **Review / Revisit Date** — when this should be re-examined, or the condition51 that would reopen it. Decisions made under today's assumptions should have an52 expiry.5354## Quality rubric5556A strong KDD:5758- **Answers first** — the decision is stated up top, not buried.59- **Shows the work** — drivers + ≥2 options with honest trade-offs, not a60 single foregone conclusion.61- **Names accountability** — explicit approvers/stakeholders, not an anonymous62 "we decided".63- **Justifies over alternatives** — explains why the chosen option won.64- **Has a revisit trigger** — a date or condition for re-examination.65- **Is honest about implications** — downstream costs and commitments, not just66 upside.6768## Common pitfalls6970- Reaching for a KDD when it's really an architectural decision (use an ADR).71- No named approvers — the decision has no accountable owner.72- Listing only the chosen option; no drivers, no alternatives.73- No revisit date — stale decisions silently outlive their assumptions.74- Restating background at length while burying the actual decision.7576## Naming & storage7778- Directory: `docs/decisions/`79- Filename: `NNNN-kebab-case-title.md`, zero-padded sequence (or date-prefixed if80 you prefer chronological ordering).81- Track status: `Proposed` → `Decided` → `Revisited` / `Superseded`.8283## Template8485Copy `templates/kdd.md` and fill it in.8687## Related8889- For architectural/technical decisions, use the **adr** skill.90- If a KDD requires a deeper design exploration first, write an **rfc** and link91 it from the Context section.
AdamAkhlaq