kaddo-kdd/kaddo/adr-writing

ADR Writing Skill

Purpose

Standardize how Architecture Decision Records are written so every decision is captured the same way and stays auditable.

When to use

When a real, consequential technical decision is being made or recognized — and only then.

Inputs

The context pack, the relevant Work Item or architecture note, and the decision being made.

Output

A single ADR (saved under knowledge/tech/decisions/) with front matter and the standard sections: context, options considered, the decision, consequences, related capabilities and related Work Items. Status is one of draft, accepted, superseded, deprecated.

Materializing from decision candidates (VS-075)

When knowledge/tech/decisions/ is empty but knowledge/tech/decision-candidates.md holds candidates, materialize each candidate as an ADR draft — copy its context and options, leave the decision and consequences as [open] for human confirmation, and record its origin with created_from: knowledge/tech/decision-candidates.md. Never mark a materialized draft accepted; acceptance is a human decision.

Rules

• One ADR = one decision. Never mix unrelated decisions.
• Never invent decisions; never write an ADR without a clear reason.
• Record alternatives honestly, including the one chosen and why (or [open] when undecided).
• Prefer narrow governed code: globs over broad ones.

Quality checklist

• Context explains why the decision was needed.
• The decision and its alternatives are explicit (or explicitly [open]).
• Consequences (positive and negative) are stated.
• Status and governed paths are present.

Example output

---
type: adr
status: draft | accepted | superseded | deprecated
date: YYYY-MM-DD
created_from: knowledge/tech/decision-candidates.md
---
 
# ADR-001 — Use INTERNAL_CRON_SECRET for internal endpoint protection
 
## Context
...
## Options Considered
...
## Decision
[open]
## Consequences
[open]
## Related Capabilities
-<domain / capability>
## Related Work Items
-<WI id>