range3/adr

ADR Writer

Capture architectural decisions from the current session and write them as new ADR files under <project_root>/docs/decisions/, following this project's MADR 4.0.0 variant. The template lives at assets/adr-template.md (next to this file).

Core principles

• Append-only. New decisions are recorded by adding new ADR files. Existing ADRs are immutable in content. The only permitted mutation is flipping status to deprecated or superseded, plus — when superseding — a single > Superseded by ADR-NNNN-... annotation line in the superseded ADR's body. Nothing else in an existing ADR may be edited.
• One decision per ADR. A large refactor that touched many files is typically still one ADR, unless multiple independent choices were made along the way.
• Confirm before writing. Always present the proposed list (new + retracting) to the user and wait for approval before touching the filesystem.
• Body language follows the session. If the conversation is in Japanese, write the ADR body, title heading, and summary value in Japanese. If English, English. Filenames remain ASCII kebab-case regardless, for portability.

What counts as an ADR-worthy decision

Record decisions that:

• Have lasting impact on architecture, codebase structure, or tooling
• Involved a real choice between alternatives
• Carry tradeoffs worth documenting for future contributors

Skip:

• Trivial implementation details (naming, single-function refactors, formatting)
• Decisions already covered by an existing ADR (check INDEX.md first)
• Bug fixes with no structural choice
• Exploratory work that was abandoned

If the session contains no qualifying decisions, tell the user plainly — do not fabricate ADRs to fill the directory.

Script invocation rule

Every call to scripts/adr.py must use absolute paths for --dir (and for the script itself), to avoid CWD-dependent behavior. Resolve <project_root> once at the start of the workflow — typically via git rev-parse --show-toplevel — and reuse it throughout.

uv run <this-skill-dir>/scripts/adr.py --dir <project_root>/docs/decisions <subcommand>

Subcommands used by this skill: init, list, reindex. (validate, get, getfile exist on the script but are not part of the standard flow.)

Workflow

1. Initialize the directory if missing

If <project_root>/docs/decisions/ does not exist:

uv run <this-skill-dir>/scripts/adr.py --dir <project_root>/docs/decisions init

2. Scan existing ADRs — INDEX.md first

Read <project_root>/docs/decisions/INDEX.md first. It contains the No / Status / Summary table for every existing ADR and is the cheapest way to see what's already on record.

Only open individual ADR-NNNN-*.md files when you actually need full content — typically to:

• Verify a session decision really duplicates an existing one
• Identify exactly which ADR a new decision retracts (and which file to edit in step 6)

If INDEX.md is missing or appears stale (e.g. file count doesn't match), run list to regenerate the same table on stdout:

uv run <this-skill-dir>/scripts/adr.py --dir <project_root>/docs/decisions list

The table does not include filenames; pair it with ls <project_root>/docs/decisions/ to map No → filename when needed.

3. Extract decision candidates from the session

Walk the session and identify distinct decisions at ADR granularity. For each candidate, work out:

• The problem or trigger
• Alternatives considered (including "status quo" / "do nothing" where relevant)
• The chosen option and the dominant reason
• The consequences — both good and bad
• Whether it retracts an existing ADR (compare against the INDEX.md summaries from step 2)

4. Confirm the plan with the user

Before any file is written or modified, present a plan and wait for confirmation. Use the session's language. Format:

記録予定:
- ADR-0007 — Adopt Biome for linting and formatting
- ADR-0008 — Switch internal API from REST to GraphQL

撤回予定:
- ADR-0004 (use-rest-internally) → superseded by ADR-0008

この内容で書き込んでよろしいですか?

Accept user edits — drop entries, merge entries, change a title, demote a superseded to deprecated, etc. Re-present the plan if changes are substantive. A reply like "OK" / "進めて" / "yes" is sufficient to proceed.

5. Write each new ADR

For each confirmed new ADR:

1. Assign the next NNNN (4-digit zero-padded, smallest unused across the directory).

2. Generate a short-title in ASCII kebab-case expressing problem + solution. Good: use-vite-react-typescript-as-frontend-stack, manage-skills-via-lock-file-and-symlinks. Bad (too generic): use-typescript, add-tests.

3. Read the template at <this-skill-dir>/assets/adr-template.md.

4. Fill the frontmatter:

   ---
   status: accepted
   created_at: 2026-05-17T13:45:00+09:00
   summary: "One short, declarative sentence — no trailing period"
   ---
   

   • status: default accepted (session decisions are already implemented). Use proposed only if the decision is explicitly tentative.
   • created_at: real current ISO 8601 timestamp with timezone offset — not midnight, not a placeholder.
   • summary: ≤ 80 chars, no trailing period, in the body language.

5. Write the body following the template's section structure. Drop optional sections (those marked <!-- This is an optional element. -->) when they add no signal — keeping empty placeholders is worse than removing them.

6. If this ADR supersedes an older one, naturally mention Supersedes ADR-NNNN-... in the body (Context, Decision Outcome, or More Information — wherever it reads best).

7. Save to <project_root>/docs/decisions/ADR-NNNN-<short-title>.md.

6. Update retracted ADRs

For each ADR the plan retires, edit only status, plus — when superseding — one annotation line. Never touch created_at, summary, the title, or any other body content.

• deprecated — decision no longer in force, no specific replacement:
  • Flip status: ... → status: deprecated. Done.
• superseded — replaced by a specific newer ADR:
  • Flip status: ... → status: superseded.
  • Insert a single quoted line right under the # Title heading (blank line above and below), before the first ## section. Use the body's language:
    • English: > Superseded by ADR-NNNN-<short-title>.
    • Japanese: > ADR-NNNN-<short-title> によって置き換えられました。

If you find yourself wanting to edit anything else in an existing ADR — stop. Either write a new ADR that records the change, or ask the user.

7. Reindex

After all writes (new files + status updates), regenerate INDEX.md:

uv run <this-skill-dir>/scripts/adr.py --dir <project_root>/docs/decisions reindex

The script validates every ADR's frontmatter against a strict schema (status ∈ {proposed, accepted, deprecated, superseded}, summary non-empty, created_at parseable as ISO 8601). If validation fails, the offending file is named in the error — fix it and rerun. INDEX.md is only rewritten when validation passes.

8. Report

One line per change — no full contents:

• New: ADR-NNNN — <title> — <summary>
• Retired: ADR-NNNN — <previous status> → <new status>[ (by ADR-MMMM)]

Filename and title rules

• File format: ADR-NNNN-<short-title>.md
• NNNN: smallest unused 4-digit number in the directory
• <short-title>: lowercase ASCII kebab-case, expressing problem + solution
• The # Heading inside the file is the same idea but readable prose, in the body language. Examples:
  • # Use Vite + React + TypeScript as the frontend stack
  • # フロントエンドスタックとして Vite + React + TypeScript を採用する

Content guidance

ADRs are reference material, not blog posts — be concise.

• Context and Problem Statement: 2–4 sentences. State the actual problem; cut background trivia.
• Decision Drivers: 3–5 bullets max. Each must have actually driven the choice.
• Considered Options: list real alternatives, including ones explicitly rejected. "Status quo" is often valid.
• Decision Outcome: lead with the chosen option and the dominant reason. One paragraph.
• Consequences: honest tradeoffs — include the bad ones. Future contributors need to know what they're paying.

Drop ### Confirmation, ## Pros and Cons of the Options, and ## More Information sections when they add no signal.

Example walkthrough

User: 「セッション終わり。今日決めたこと、ADRに残しておいて。」

1. Resolve <project_root> via git rev-parse --show-toplevel → /home/me/myproj.

2. Read /home/me/myproj/docs/decisions/INDEX.md → highest existing is ADR-0006.

3. Identify two session decisions: Biome adoption, and switching the internal API from REST to GraphQL. The GraphQL switch retracts ADR-0004 (which adopted REST).

4. Present the plan:

   記録予定:
   - ADR-0007 — Adopt Biome for linting and formatting
   - ADR-0008 — Switch internal API from REST to GraphQL
   
   撤回予定:
   - ADR-0004 (use-rest-internally) → superseded by ADR-0008
   
   この内容で書き込んでよろしいですか?
   

5. User: 「OK」

6. Write ADR-0007-adopt-biome-for-linting-and-formatting.md and ADR-0008-switch-internal-api-from-rest-to-graphql.md, both status: accepted, body in Japanese (session language). ADR-0008's Context section mentions "Supersedes ADR-0004-use-rest-internally".

7. Edit ADR-0004-use-rest-internally.md: flip status: accepted → status: superseded, insert > ADR-0008-switch-internal-api-from-rest-to-graphql によって置き換えられました。 right under the # Title. Nothing else changes.

8. Run:

   uv run <this-skill-dir>/scripts/adr.py --dir /home/me/myproj/docs/decisions reindex
   

9. Report:

   • 新規: ADR-0007 — Adopt Biome for linting and formatting — ESLint+Prettier から Biome に統一して CI 時間を短縮
   • 新規: ADR-0008 — Switch internal API from REST to GraphQL — クライアント側のover-fetching解消のためGraphQLへ移行
   • 撤回: ADR-0004 — accepted → superseded (by ADR-0008)