thkt/adr

/adr - Architecture Decision Record Creator

Input

• Decision title: $ARGUMENTS (specific action like "Adopt X for Y")
• If $ARGUMENTS is empty → select via AskUserQuestion
• Storage: <git-root>/docs/decisions/ (MADR v4 default, enforced)
• Override: set ADR_DIR env var for non-standard locations

Use $ARGUMENTS to capture full input. $N is 0-indexed split ($0 first word, $1 second), so $1 is unsuitable for full multi-word titles.

Title Prompt

| Question | Options | | ------------- | ------------------------------ | | Decision type | New decision / Update existing |

If "Update existing" → list recent ADRs in <git-root>/docs/decisions/ for selection via AskUserQuestion.

Adoption Gate

Before starting the 6-Phase Process, confirm all three conditions hold. If any one is missing, skip the ADR and record the decision somewhere lighter.

| # | Condition | Failing example | | - | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | 1 | Hard to reverse. Changing the decision later carries meaningful cost | Library swap with one isolated import boundary | | 2 | Surprising without context. A future reader will ask "why this way?" | Choosing the only option the framework supports | | 3 | Result of a real trade-off. Genuine alternatives existed and one was picked for specific reasons | Following an established team convention by default |

| Outcome | Demote to | | ------------------------ | ------------------------------------------------------------------------------------ | | Conditions 1 or 2 fail | CONTEXT.md entry (or equivalent project glossary / design notes) | | Only condition 3 fails | Commit message body (record the rationale alongside the change) | | All three pass | Proceed to the 6-Phase Process below |

Reference: mattpocock/skills grill-with-docs SKILL.md Offer ADRs sparingly.

6-Phase Process

| Phase | Actions | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1. Pre-Check | Run ${CLAUDE_SKILL_DIR}/scripts/pre-check.sh "$TITLE". Parse JSON for number, filename, slug, adr_dir, similar_adrs | | 2. Template | Run ${CLAUDE_SKILL_DIR}/scripts/select-adr-template.sh "$TITLE". stdout returns the template name | | 3. References | Gather project docs, issues, external resources | | 4. Validate | Run ${CLAUDE_SKILL_DIR}/scripts/validate-adr.sh "$ADR_FILE" after writing. exit 0 + empty errors[] = pass. warnings[] advisory | | 5. Index | Run ${CLAUDE_SKILL_DIR}/scripts/update-index.sh to regenerate index README | | 6. Recovery | Handle missing dirs, duplicates, missing sections |

Directory Resolution

| Step | Source | Behavior | | ---- | ------------------------------- | ---------------------------------------------------------------------- | | 1 | $ADR_DIR env var | Use as-is when set | | 2 | git rev-parse --show-toplevel | Resolve to <git-root>/docs/decisions/ | | 3 | Not in a git repo | Error and exit. ADRs require a versioned project root | | 4 | Skill-self protection | If target contains SKILL.md, error (prevents writing into skill dir) |

Template Selection

${CLAUDE_SKILL_DIR}/scripts/select-adr-template.sh "$TITLE" is a heuristic hint, not authority. Pick the template by the decision's intent; use the script as a starting suggestion.

| Template | Use Case | Required MADR v4 sections | | -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | technology-selection | Library, framework choices | Title, Context and Problem Statement, Considered Options (2+), Decision Outcome | | architecture-pattern | Structure, design policy | Title, Context and Problem Statement, Considered Options (2+), Decision Outcome | | process-change | Workflow, rule changes | Title, Context and Problem Statement, Considered Options (2+), Decision Outcome | | deprecation | Retiring technology | Title, Context and Problem Statement, Considered Options (2+), Decision Outcome, More Information (deprecation-specific) |

Keyword Triggers

Priority on multiple matches: deprecation > process-change > architecture-pattern > technology-selection (default).

| Template | English keywords | Japanese keywords | | -------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------ | | deprecation | deprecate, remove, retire, sunset, phase out | 廃止, 非推奨, 削除, 撤廃 | | process-change | process, workflow, procedure, standard, policy, rule, merge, branch, rebase, squash, review, ci | プロセス, ワークフロー, 規約, 規則, 手順 | | architecture-pattern | pattern, architecture, design, structure, template, gateway, layer, monorepo, boundary | パターン, アーキテクチャ, 設計, 構造, 統一 | | technology-selection | adopt, choose, use, select (default when nothing else matches) | (default) |

Override Rule

Override the script output when it does not match the decision's intent. Note the reason in the ADR's Context. The template you pick determines the required sections.

| Title example | Script returns | Override to | | ---------------------------------------------- | -------------------- | -------------------- | | Migrate from squash-merge to rebase-merge | technology-selection | process-change | | Replace REST gateway with tRPC monorepo layer | technology-selection | architecture-pattern |

Directory Structure

<git-root>/
└── docs/
    └── decisions/
        ├── README.md   # Auto-generated index
        ├── 0001-*.md   # Sequential numbering (MADR nnnn-title)
        └── 0002-*.md   # (next)

Rules

| Rule | Detail | | ------------ | ---------------------------------------------------------------------------- | | Immutability | Decision content immutable once accepted. See Supersede Procedure | | Brevity | Per-template line budget. See Line Budget | | Frontmatter | YAML frontmatter optional. See Frontmatter Conventions | | Confirmation | ### Confirmation under Decision Outcome describes how to verify compliance |

Frontmatter Conventions (MADR v4)

---
status: "proposed | rejected | accepted | deprecated | superseded by ADR-NNNN"
date: 2026-04-25
decision-makers: list of names or roles
consulted: subject-matter experts (two-way)
informed: stakeholders kept up-to-date (one-way)
---

| Field | Required | Notes | | --------------- | -------- | --------------------------------------------------------------- | | status | Optional | YAML quotes required. Identifier only, no links | | date | Optional | YYYY-MM-DD of creation; updated only when the ADR is superseded | | decision-makers | Optional | Renamed from deciders in v4 |

Supersede Procedure

When a new ADR replaces an existing one:

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

Only status and date change in the old ADR. Decision content stays as-is.

Line Budget

| Templates | Total budget | Per section | | ------------------------------------------- | ------------ | ----------------------------------------------------------------- | | technology-selection / architecture-pattern | ~80 lines | Context 3 lines, Options 3-5 lines each, Consequences 2-3 bullets | | process-change / deprecation | ~100 lines | Same per-section guidance |

Output

• <git-root>/docs/decisions/XXXX-slug.md (ADR 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 | | Templates | ${CLAUDE_SKILL_DIR}/templates/ | | Scripts | ${CLAUDE_SKILL_DIR}/scripts/ |