thkt/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/ |