/dr - Decision Record Creation
Input
Take the decision title from $ARGUMENTS. If empty, confirm New decision / Update existing via AskUserQuestion. For New decision ask for the title; for Update existing, list recent DRs in <git-root>/docs/decisions/ for selection (§ Updating an Existing DR). Shape a title you are creating into a specific action like "Adopt X for Y", keeping it 5-64 characters and free of /:*?"<>|. The archive defaults to <git-root>/docs/decisions/, and the DR_DIR env var moves it.
Adoption Gate
Proceed to the process only when all three conditions below hold. When one is missing, skip the DR and apply the table top to bottom, leaving the decision where the first matching row says.
| Condition |
Where it goes when missing |
| Hard to reverse. Changing the decision later carries meaningful cost |
A design note in the project, or the commit message body when there is none |
| Surprising without context. A future reader will ask "why this way?" |
A design note in the project, or the commit message body when there is none |
| Result of a real trade-off. Genuine alternatives existed and one was picked for specific reasons |
The commit message body |
Process
| Step |
Stage |
Actions |
| 1 |
Pre-Check |
Run ${CLAUDE_SKILL_DIR}/scripts/pre-check.ts "$TITLE". What it consumes from the return is dr_dir and filename (where to write), date (frontmatter), and similar_drs (duplicate check) |
| 2 |
Type |
Determine the decision type by the decision's intent and pick its recommended topics (§ Decision Type) |
| 3 |
Sources |
Gather project docs, issues, external resources |
| 4 |
Draft |
Copy ${CLAUDE_SKILL_DIR}/templates/madr-template.md into dr_dir under the name filename and fill it from what was gathered (§ YAML Frontmatter) |
| 5 |
Challenge |
Only for a DR that carves an exception into an existing DR's principle or supersedes one, run /challenge and record the verdict and the condition it holds under as one line in More Information |
| 6 |
Validate |
Run ${CLAUDE_SKILL_DIR}/scripts/validate-dr.ts "$DR_FILE". exit 0 passes. What failed lands in errors[], and warnings[] is advisory |
| 7 |
Index |
Run ${CLAUDE_SKILL_DIR}/scripts/update-index.ts to regenerate dr_dir/README.md |
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. Reassessment Triggers goes into More Information whatever the type, which makes it an h3 in a new DR. Whoever proposes removing or merging existing structure reads that section to judge, so a missing one leaves that judgment nothing to read.
| Decision type |
Use Case |
Recommended topics |
| technology-selection |
Library, framework choices |
Migration Strategy, Rollback Plan, Success Criteria |
| architecture-pattern |
Structure, design policy |
Architecture Diagram, Quality Attributes, Trade-offs |
| process-change |
Workflow, rule changes |
Before / After comparison, Transition Plan, Review Schedule |
| deprecation |
Retiring technology |
Deprecation Target, Migration Plan, Deprecation Warning Period, Rollback Plan |
YAML Frontmatter
The frontmatter is optional. When it is written, it uses the fields below.
| Field |
Notes |
| status |
Pick from the Status lifecycle in ${CLAUDE_SKILL_DIR}/references/madr-format.md. YAML quotes required; no links |
| date |
YYYY-MM-DD of creation; updated only when the DR is superseded |
| decision-makers |
List of names or roles. Renamed from deciders in v4 |
| consulted |
Subject-matter experts; two-way exchange |
| informed |
Stakeholders kept up-to-date; one-way |
Updating an Existing DR
When the status is proposed, edit the body directly and run Validate and Index. From accepted onward, replace it with a new DR through the steps below. Only status and date change in the old DR; the decision content stays.
- Create the new DR through the process. The Adoption Gate does not apply, since the decision it replaces is already on record
- Cite the predecessor in the new DR's More Information (e.g.
Supersedes DR-NNNN)
- In the old DR, change
status: to superseded by DR-NNNN
- Update the old DR's
date: to today
- Run ${CLAUDE_SKILL_DIR}/scripts/update-index.ts to refresh the index
Error Handling
Each script reports its failure as JSON or on stderr. Handle them per the table.
| Error |
Treatment |
| Reported as outside a git repository |
Set DR_DIR to name the archive explicitly |
| Reported as an archive holding SKILL.md |
It points at a skill directory, so redirect DR_DIR to the archive |
similar_drs is non-empty |
Present the duplicates and confirm whether to proceed or switch to an update (§ Updating an Existing DR) |
errors[] comes back non-empty |
Fix what it names and run Validate again |
References
| What you are unsure of |
Resource |
| Whether to keep or drop an optional section |
${CLAUDE_SKILL_DIR}/references/madr-format.md |
| What it takes to explain a decision fully |
${CLAUDE_SKILL_DIR}/references/fowler-adr.md |
1---2name: dr3description: Create a Decision Record (DR) in MADR v4 format with automatic numbering. Its subject is not limited to architecture; it covers every decision that is hard to reverse and surprising without context.4---56# /dr - Decision Record Creation78## Input910Take the decision title from `$ARGUMENTS`. If empty, confirm New decision / Update existing via AskUserQuestion. For New decision ask for the title; for Update existing, list recent DRs in `<git-root>/docs/decisions/` for selection (§ Updating an Existing DR). Shape a title you are creating into a specific action like "Adopt X for Y", keeping it 5-64 characters and free of `/:*?"<>|`. The archive defaults to `<git-root>/docs/decisions/`, and the `DR_DIR` env var moves it.1112## Adoption Gate1314Proceed to the process only when all three conditions below hold. When one is missing, skip the DR and apply the table top to bottom, leaving the decision where the first matching row says.1516| Condition | Where it goes when missing |17| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |18| Hard to reverse. Changing the decision later carries meaningful cost | A design note in the project, or the commit message body when there is none |19| Surprising without context. A future reader will ask "why this way?" | A design note in the project, or the commit message body when there is none |20| Result of a real trade-off. Genuine alternatives existed and one was picked for specific reasons | The commit message body |2122## Process2324| Step | Stage | Actions |25| ---- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |26| 1 | Pre-Check | Run ${CLAUDE_SKILL_DIR}/scripts/pre-check.ts "$TITLE". What it consumes from the return is `dr_dir` and `filename` (where to write), `date` (frontmatter), and `similar_drs` (duplicate check) |27| 2 | Type | Determine the decision type by the decision's intent and pick its recommended topics (§ Decision Type) |28| 3 | Sources | Gather project docs, issues, external resources |29| 4 | Draft | Copy ${CLAUDE_SKILL_DIR}/templates/madr-template.md into `dr_dir` under the name `filename` and fill it from what was gathered (§ YAML Frontmatter) |30| 5 | Challenge | Only for a DR that carves an exception into an existing DR's principle or supersedes one, run `/challenge` and record the verdict and the condition it holds under as one line in More Information |31| 6 | Validate | Run ${CLAUDE_SKILL_DIR}/scripts/validate-dr.ts "$DR_FILE". exit 0 passes. What failed lands in `errors[]`, and `warnings[]` is advisory |32| 7 | Index | Run ${CLAUDE_SKILL_DIR}/scripts/update-index.ts to regenerate `dr_dir/README.md` |3334## Decision Type3536The 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. Reassessment Triggers goes into More Information whatever the type, which makes it an h3 in a new DR. Whoever proposes removing or merging existing structure reads that section to judge, so a missing one leaves that judgment nothing to read.3738| Decision type | Use Case | Recommended topics |39| -------------------- | -------------------------- | ----------------------------------------------------------------------------- |40| technology-selection | Library, framework choices | Migration Strategy, Rollback Plan, Success Criteria |41| architecture-pattern | Structure, design policy | Architecture Diagram, Quality Attributes, Trade-offs |42| process-change | Workflow, rule changes | Before / After comparison, Transition Plan, Review Schedule |43| deprecation | Retiring technology | Deprecation Target, Migration Plan, Deprecation Warning Period, Rollback Plan |4445## YAML Frontmatter4647The frontmatter is optional. When it is written, it uses the fields below.4849| Field | Notes |50| --------------- | --------------------------------------------------------------------------------------------------------------- |51| status | Pick from the Status lifecycle in ${CLAUDE_SKILL_DIR}/references/madr-format.md. YAML quotes required; no links |52| date | YYYY-MM-DD of creation; updated only when the DR is superseded |53| decision-makers | List of names or roles. Renamed from `deciders` in v4 |54| consulted | Subject-matter experts; two-way exchange |55| informed | Stakeholders kept up-to-date; one-way |5657## Updating an Existing DR5859When the status is proposed, edit the body directly and run Validate and Index. From accepted onward, replace it with a new DR through the steps below. Only `status` and `date` change in the old DR; the decision content stays.60611. Create the new DR through the process. The Adoption Gate does not apply, since the decision it replaces is already on record622. Cite the predecessor in the new DR's More Information (e.g. `Supersedes DR-NNNN`)633. In the old DR, change `status:` to `superseded by DR-NNNN`644. Update the old DR's `date:` to today655. Run ${CLAUDE_SKILL_DIR}/scripts/update-index.ts to refresh the index6667## Error Handling6869Each script reports its failure as JSON or on stderr. Handle them per the table.7071| Error | Treatment |72| --------------------------------------- | -------------------------------------------------------------------------------------------------------- |73| Reported as outside a git repository | Set `DR_DIR` to name the archive explicitly |74| Reported as an archive holding SKILL.md | It points at a skill directory, so redirect `DR_DIR` to the archive |75| `similar_drs` is non-empty | Present the duplicates and confirm whether to proceed or switch to an update (§ Updating an Existing DR) |76| `errors[]` comes back non-empty | Fix what it names and run Validate again |7778## References7980| What you are unsure of | Resource |81| ------------------------------------------- | --------------------------------------------- |82| Whether to keep or drop an optional section | ${CLAUDE_SKILL_DIR}/references/madr-format.md |83| What it takes to explain a decision fully | ${CLAUDE_SKILL_DIR}/references/fowler-adr.md |
thkt