ADR System Skill

This skill enables Claude to work with Architecture Decision Records (ADRs) managed by DECIDER.

Overview

This repository uses DECIDER to manage ADRs. ADRs document significant architectural decisions with structured metadata that enables automated tooling and AI agent consumption.

Mandatory Rationale Pattern

ALL ADRs MUST use the explicit rationale pattern. This is enforced by the CLI.

For Adopted Decisions

The chosen option MUST include:

### [Option Name]: Adopted

**Adopted because:**
- Concrete reason tied to decision drivers
- Technical, operational, or strategic justification

**Adopted despite:**
- Known downside we consciously accepted
- Trade-off compared to alternatives

For Rejected Alternatives

Each rejected option MUST include:

### [Option Name]: Rejected

**Rejected because:**
- Concrete reason for rejection
- How it failed to meet decision drivers

**Rejected despite:**
- Legitimate strength of this option
- Benefit that made it attractive

Prohibited Patterns

• DO NOT use only pros/cons tables
• DO NOT omit "despite" sections
• DO NOT use vague language like "better fit"
• DO NOT imply rejection without explicit rationale

ADR Format

ADRs use Markdown with YAML frontmatter:

---
adr_id: ADR-NNNN
title: "Decision Title"
status: proposed|adopted|rejected|deprecated|superseded
date: YYYY-MM-DD
scope:
  paths:
    - "path/to/affected/**"
tags:
  - relevant-tag
constraints:
  - "Rule that MUST be followed"
invariants:
  - "Property that must always hold"
supersedes: []
superseded_by: []
related_adrs: []
---

# ADR-NNNN: Decision Title

## Context

Decision drivers:
- Driver 1
- Driver 2

## Decision

### [Chosen Option]: Adopted

**Adopted because:**
- Reason 1
- Reason 2

**Adopted despite:**
- Trade-off 1
- Trade-off 2

## Alternatives Considered

### [Alternative A]: Rejected

**Rejected because:**
- Reason 1

**Rejected despite:**
- Strength 1

## Consequences

**Positive:**
- Benefit 1

**Negative:**
- Cost 1

Key Concepts

Scope Paths

Glob patterns that indicate which parts of the codebase an ADR applies to. Used by

decider check diff

to find relevant ADRs.

Constraints

Rules that MUST be followed when working in the affected scope. These are prescriptive.

Invariants

Properties that must ALWAYS be true. These are conditions to preserve.

Status Lifecycle

• proposed

  → Under discussion

• adopted

  → Approved and in effect

• rejected

  → Considered but not adopted

• deprecated

  → Was adopted, now discouraged

• superseded

  → Replaced by another ADR

Commands

# Initialize ADR structure
decider init

# Create new ADR (includes rationale pattern template)
decider new "Title" --tags foo,bar --paths "src/**"

# List ADRs
decider list
decider list --status adopted --tag security

# Show ADR details
decider show ADR-0001

# Validate ADRs (warns on missing rationale pattern)
decider check adr

# Validate ADRs strictly (fails on missing rationale pattern)
decider check adr --strict

# Check which ADRs apply to changes
decider check diff --base main

# Explain why ADRs apply
decider explain --base main

# Update index
decider index

Working with ADRs

Before Making Changes

1. Run

   decider check diff --base main

   to find applicable ADRs
2. Read the constraints and invariants
3. Ensure your changes comply

Creating a New ADR

1. Run

   decider new "Title" --tags ... --paths ...

2. Fill in the Context section with decision drivers
3. Document the chosen option with:
   • "Adopted because:" (concrete reasons)
   • "Adopted despite:" (trade-offs accepted)
4. Document each rejected alternative with:
   • "Rejected because:" (concrete reasons)
   • "Rejected despite:" (acknowledged strengths)
5. Run

   decider check adr --strict

   to validate
6. Run

   decider index

   to update the index

Reviewing an ADR

Check that:

• "Adopted because:" section exists with concrete reasons
• "Adopted despite:" section exists with trade-offs
• Each alternative has "Rejected because:" and "Rejected despite:"
• No prose-only sections without the pattern

• decider check adr --strict

  passes

Index File

The

docs/adr/index.yaml

file is auto-generated and provides quick access to ADR metadata:

generated_at: "2026-01-16T10:00:00Z"
adr_count: 5
adrs:
  - adr_id: ADR-0001
    title: "Decision Title"
    status: adopted
    date: "2026-01-16"
    tags: [foundation]
    scope_paths: ["src/**"]
    file: "0001-decision-title.md"

Never edit this file manually. Always use

decider index

to regenerate it.