dr

/dr - Decision Record Creator

Input

Take the decision title from $ARGUMENTS and shape it into a specific action like "Adopt X for Y". If empty, confirm New decision / Update existing via AskUserQuestion; for Update existing, list recent DRs in <git-root>/docs/decisions/ for selection. To change the storage location, set the DR_DIR env var before running.

Adoption Gate

Proceed to the 6-Phase Process only when all three conditions hold. Otherwise skip the DR; if condition 1 or 2 is missing, record the decision as a CONTEXT.md entry or an equivalent design note, and if only condition 3 is missing, record it in the commit message body.

1. Hard to reverse. Changing the decision later carries meaningful cost
2. Surprising without context. A future reader will ask "why this way?"
3. Result of a real trade-off. Genuine alternatives existed and one was picked for specific reasons

Rules

Rule	Detail
Immutability	Decision content immutable once accepted. See Supersede Procedure
Brevity	Per-type size limit. See Decision Type
Frontmatter	YAML frontmatter optional. See YAML Frontmatter
Confirmation	### Confirmation under Decision Outcome describes how to verify compliance

YAML Frontmatter (MADR v4)

Field	Required	Notes
status	No	One of proposed, rejected, accepted, deprecated, superseded by DR-NNNN. YAML quotes required; no links
date	No	YYYY-MM-DD of creation; updated only when the DR is superseded
decision-makers	No	List of names or roles. Renamed from deciders in v4
consulted	No	Subject-matter experts; two-way exchange
informed	No	Stakeholders kept up-to-date; one-way

Supersede Procedure

When a new DR replaces an existing one. Only status and date change in the old DR; decision content stays as-is.

Step	Action
1	Create the new DR via the normal 6-Phase Process
2	New DR's More Information cites the predecessor (e.g. Supersedes DR-NNNN)
3	In the old DR, change status: to superseded by DR-NNNN
4	Update old DR's date: to today
5	Run ${CLAUDE_SKILL_DIR}/scripts/update-index.py to refresh the index

Decision Type

The decision type only affects which recommended More Information topics to include. Per-section guidance is common to all types: Context 3 lines, Options 3-5 lines each, Consequences 2-3 bullets.

Decision type	Use Case	Line limit	Recommended topics
technology-selection	Library, framework choices	80 lines	Migration Strategy, Rollback Plan, Success Criteria
architecture-pattern	Structure, design policy	80 lines	Architecture Diagram, Quality Attributes, Trade-offs
process-change	Workflow, rule changes	100 lines	Before / After comparison, Transition Plan, Review Schedule
deprecation	Retiring technology	100 lines	Deprecation Target, Migration Plan, Deprecation Warning Period, Rollback Plan

6-Phase Process

Step	Phase	Actions
1	Pre-Check	Run ${CLAUDE_SKILL_DIR}/scripts/pre-check.py "$TITLE". If similar_drs is non-empty, confirm the potential duplicate with the user before proceeding
2	Type	Determine the decision type by the decision's intent and pick recommended topics from the Decision Type table
3	References	Gather project docs, issues, external resources
4	Validate	Run ${CLAUDE_SKILL_DIR}/scripts/validate-dr.py "$DR_FILE" after writing. exit 0 + empty errors[] = pass. warnings[] advisory
5	Index	Run ${CLAUDE_SKILL_DIR}/scripts/update-index.py to regenerate index README
6	Recovery	Handle missing dirs, duplicates, missing sections

Output

Path	Description
<git-root>/docs/decisions/XXXX-slug.md	DR file
<git-root>/docs/decisions/README.md	Auto-generated index

References

Topic	Resource
MADR	${CLAUDE_SKILL_DIR}/references/madr-format.md
Fowler	${CLAUDE_SKILL_DIR}/references/fowler-adr.md
Template	${CLAUDE_SKILL_DIR}/templates/madr-template.md
Scripts	${CLAUDE_SKILL_DIR}/scripts/