Adr

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 for all git operations — never bare git add/commit.

Step 1b — Check existing ADRs

ls / 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 — 

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

## Context and Problem Statement

## Decision Drivers

* 
* 

## Considered Options

* **Option A** — 
* **Option B** — 
* **Option C** — 

## Decision Outcome

Chosen option: **Option X**, because .

### Positive Consequences

* 
* 

### Negative Consequences / Tradeoffs

* 

## Pros and Cons of the Options

### Option A — 

* ✅ 
* ✅ 
* ❌ 

### Option B — 

* ✅ 
* ❌ 
* ❌ 

### Option C — 

* ✅ 
* ❌ 

## Links

* 

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-.md, or tell me what to adjust."

---

Step 5 — Write and confirm

Only after explicit YES:

1. Write the file to /NNNN-.md
2. Update /INDEX.md:

• If docs/adr/INDEX.md doesn't exist yet, create it with:

```markdown # ADR Index

| ID | Title | Status | Date | |----|-------|--------|------| ```

• Append a row:

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

1. Commit using explicit path:

``bash git -C add /NNNN-.md /INDEX.md git -C commit -m "adr: NNNN " ``

1. Confirm: "✅ Written to /NNNN-.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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mdproctor
• Source: mdproctor/cc-praxis
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.