adr

name	adr
description	Use when recording architectural decisions: user says "create an ADR", "document why we chose X", significant technical choices are made, dependency-update proposes major version upgrades, or update-design captures new components.

Architecture Decision Record (ADR) Helper

You are an expert at capturing architectural decisions clearly and concisely using the MADR (Markdown Any Decision Records) format. ADRs live in docs/adr/ alongside DESIGN.md.

Core Rules

• ADRs are append-only — never delete or substantially rewrite an accepted ADR. If a decision is superseded, update its status to "Superseded by [ADR-NNNN]" and create a new ADR.
• Keep ADRs concise. The goal is to capture why, not to write an essay.
• Never write an ADR to a file without explicit user confirmation.
• Number ADRs sequentially: NNNN-short-title.md (e.g. 0001-use-quarkus-flow.md).
• Titles use kebab-case, all lowercase.

Workflow

Step 1 — Resolve write destination

Before checking existing ADRs, resolve where to write using the three-layer routing cascade:

# Layer 3: workspace CLAUDE.md per-artifact override
grep -A 20 "^## Routing$" CLAUDE.md 2>/dev/null | grep "^| adr"

# Layer 2: global default
grep -A 5 "^## Routing$" "$HOME/.claude/CLAUDE.md" 2>/dev/null | grep "Default destination"

# Layer 1: built-in default → project (docs/adr/)

Resolve paths — run the bundled context script:

python3 ~/.claude/skills/project-init/ctx.py

Use WORKSPACE and PROJECT from the output as concrete strings in all subsequent commands.

Resolved destination	Write to	git -C path
workspace	$WORKSPACE/adr/	$WORKSPACE
project (default)	$PROJECT/docs/adr/	$PROJECT

Use git -C <resolved-path> for all git operations — never bare git add/commit.

Step 1b — Check existing ADRs

ls <resolved-adr-dir>/ 2>/dev/null || echo "No ADRs yet"

Determine the next sequence number. If no ADRs exist, start at 0001.

Step 2 — Gather context

If the user hasn't provided enough context, ask for:

• What decision was made?
• What problem does it solve?
• What alternatives were considered and why were they rejected?
• Any consequences or tradeoffs worth noting?

For decisions arising from dependency-update or update-design, extract context from those proposals automatically.

Step 3 — Draft the ADR

Use this MADR template. Always replace YYYY-MM-DD with today's date (available in session context) — never show the placeholder to the user.

# NNNN — <Short noun phrase title>

Date: YYYY-MM-DD
Status: Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN]

## Context and Problem Statement

<1–3 sentences: what situation or problem prompted this decision?>

## Decision Drivers

* <Key constraint, requirement, or goal>
* <Another driver>

## Considered Options

* **Option A** — <one-line description>
* **Option B** — <one-line description>
* **Option C** — <one-line description>

## Decision Outcome

Chosen option: **Option X**, because <brief rationale>.

### Positive Consequences

* <Benefit>
* <Benefit>

### Negative Consequences / Tradeoffs

* <Tradeoff or risk>

## Pros and Cons of the Options

### Option A — <name>

* ✅ <Pro>
* ✅ <Pro>
* ❌ <Con>

### Option B — <name>

* ✅ <Pro>
* ❌ <Con>
* ❌ <Con>

### Option C — <name>

* ✅ <Pro>
* ❌ <Con>

## Links

* <Related ADR, issue, PR, or doc — optional>

Step 4 — Propose for review

Show the full ADR draft and the target filename, then ask:

"Does this look good? Reply YES to write it to docs/adr/NNNN-<title>.md, or tell me what to adjust."

---

Step 5 — Write and confirm

Only after explicit YES:

1. Write the file to <resolved-adr-dir>/NNNN-<title>.md
2. Update <resolved-adr-dir>/INDEX.md:
   • If docs/adr/INDEX.md doesn't exist yet, create it with:

     # ADR Index
     
     | ID | Title | Status | Date |
     |----|-------|--------|------|
     

   • Append a row:

     | NNNN | [Title](NNNN-title.md) | Accepted | YYYY-MM-DD |
     

3. Commit using explicit path:

   git -C <resolved-path> add <resolved-adr-dir>/NNNN-<title>.md <resolved-adr-dir>/INDEX.md
   git -C <resolved-path> commit -m "adr: NNNN <title>"
   

4. Confirm: "✅ Written to <resolved-adr-dir>/NNNN-<title>.md"

Step 6 — Suggest an ADR when appropriate

Proactively suggest creating an ADR when you observe:

Trigger	Example
Major version upgrade	Quarkus 3.x → 4.x
Adopting a new extension or library	Adding quarkus-flow, LangChain4j
Choosing between two viable patterns	Java DSL vs YAML workflow definitions
Deliberately deviating from a default	Choosing MockServer over Mockito
A decision with future maintainers in mind	Thread model choice, persistence strategy
Reversing or superseding a past decision	Changing from one messaging broker to another

Don't suggest an ADR for routine decisions with no meaningful alternatives (e.g. adding a utility method, bumping a patch version).

Not decided yet? If a significant question has surfaced but the team hasn't reached a conclusion, suggest idea-log instead — park it until it's ready to become a decision.

---

ADR Lifecycle Decision Flow

flowchart TD
    Significant_decision_made((Significant decision made))
    Create_new_ADR[Create new ADR]
    Status__Accepted[Status: Accepted]
    Decision_still_valid_{Decision still valid?}
    Still_relevant_{Still relevant?}
    Better_approach_found_{Better approach found?}
    Mark_Superseded[Mark Superseded]
    Mark_Deprecated[Mark Deprecated]
    Create_new_ADR__replacement_["Create new ADR (replacement)"]
    Continue_using[Continue using]
    Significant_decision_made --> Create_new_ADR
    Create_new_ADR --> Status__Accepted
    Status__Accepted -->|time passes| Decision_still_valid_
    Decision_still_valid_ -->|"yes (still applies)"| Continue_using
    Decision_still_valid_ -->|no| Still_relevant_
    Still_relevant_ -->|yes| Better_approach_found_
    Still_relevant_ -->|"no (obsolete)"| Mark_Deprecated
    Better_approach_found_ -->|yes| Mark_Superseded
    Better_approach_found_ -->|no| Mark_Deprecated
    Mark_Superseded --> Create_new_ADR__replacement_

Status	Meaning
Proposed	Draft, not yet agreed
Accepted	Decision agreed and in effect
Deprecated	No longer relevant but not replaced
Superseded by [ADR-NNNN]	Replaced by a newer decision

When superseding an ADR:

1. Update the old ADR's status line to Superseded by [ADR-NNNN]
2. Create the new ADR referencing the old one in its Links section

Common Pitfalls

Mistake	Why It's Wrong	Fix
Deleting or rewriting accepted ADRs	Erases decision history	Mark as superseded, create new ADR
Writing essay-length ADRs	Too long to read, defeats purpose	Keep concise - capture why, not everything
Title includes solution	"ADR-001: Use PostgreSQL" is conclusion, not decision	"ADR-001: Database Selection"
Using UPPERCASE.md or CamelCase.md	Inconsistent naming conventions	Use nnnn-kebab-case-title.md
Skipping "Considered Options" section	Doesn't show what was evaluated	List 2-3 real alternatives considered
Creating ADR after implementing	Decision already made, ADR is theater	Write ADR when decision is made, not after
No consequences section	Hides tradeoffs and risks	Always list both positive and negative consequences
ADR documents routine decisions	Signal-to-noise ratio drops	Only for non-obvious decisions with alternatives

Success Criteria

ADR creation is complete when:

• ✅ User has confirmed ADR content with YES
• ✅ ADR written to docs/adr/NNNN-title.md
• ✅ Status set to "Accepted" (or "Proposed" if needs review)
• ✅ All sections filled (Context, Decision, Consequences, Alternatives, Links)
• ✅ File committed (staged with related code changes)

Not complete until ADR file exists and is committed.

Skill Chaining

Invoked by: [dependency-update] when major version upgrades or new extensions are proposed, [update-design] when significant new components are captured, [idea-log] when a parked idea is promoted to a formal decision

Invokes: [git-commit] to stage and commit the ADR (routes to git-commit, git-commit, etc. per CLAUDE.md project type)

Can be followed by: [write-content] — after a major architectural decision is recorded, the user may want to narrate the story of how that decision was reached (offered, not automatic)

Not decided yet? Use idea-log to park the question first; promote to adr when the decision is made.

Can be invoked independently: User can run /adr or say "create an ADR" directly when making architectural decisions