adr

name	adr
description	Create and manage Architecture Decision Records using the Michael Nygard format. Supports new ADR creation, retrospective analysis to document existing decisions, superseding, deprecating, and index generation. Use when you need to document architecture decisions, record technical choices, explain why a technology was chosen, or create decision logs.
version	2.0.0
category	docs
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Create or manage Architecture Decision Records for this project.

INPUT: $ARGUMENTS

Accepted arguments:

• A decision description (e.g., "Use PostgreSQL over MongoDB for primary datastore") Creates a new ADR for this decision.
• retrospective or retro: Analyze the codebase and generate ADRs for decisions already made but not documented.
• index: Regenerate the ADR index file.
• supersede <N> <new decision>: Create a new ADR that supersedes ADR-N.
• deprecate <N>: Mark ADR-N as deprecated.
• list: List all existing ADRs with their statuses.

If no arguments provided, run in retrospective mode.

============================================================ PHASE 1: DIRECTORY SETUP

Step 1.1 -- Initialize ADR Directory

Check if docs/adr/ exists. If not, create it.

Check for ADRs in alternative locations:

• adr/
• docs/decisions/
• decisions/
• doc/adr/

If found in an alternative location, use that location instead of creating a new one.

Step 1.2 -- Determine Next ADR Number

Scan existing ADR files matching the pattern NNNN-*.md (e.g., 0001-use-postgresql.md). Find the highest number and increment by 1 for the next ADR. If no ADRs exist, start at 0001.

Step 1.3 -- Read Existing ADRs

Read all existing ADR files to understand:

• What decisions have already been documented
• Current statuses (proposed, accepted, deprecated, superseded)
• Cross-references between ADRs

============================================================ PHASE 2: NEW ADR CREATION

When creating a new ADR from a decision description:

Step 2.1 -- Research the Decision

Analyze the codebase to gather context for the decision:

• Read config files related to the technology choice
• Look for alternatives that were considered (comments, TODOs, removed code)
• Identify what the decision affects (which files, modules, services)
• Check git history for when the decision was implemented

Step 2.2 -- Write ADR

Use the Michael Nygard format:

# [ADR-NNNN] [Title: Short Decision Statement]

**Date:** YYYY-MM-DD

**Status:** [proposed | accepted | deprecated | superseded by [ADR-XXXX](XXXX-title.md)]

## Context

[What is the issue that we're seeing that is motivating this decision or change?
Describe the forces at play: technical, political, social, project-specific.
These forces are likely in tension and should be called out as such.
State facts, not opinions. 2-4 paragraphs.]

## Decision

[What is the change that we're proposing and/or doing?
State the decision clearly and unambiguously.
Use active voice: "We will use X" not "X should be used."
1-2 paragraphs.]

## Consequences

[What becomes easier or more difficult to do because of this change?
Include both positive and negative consequences.
Be honest about trade-offs.

**Positive:**
- [consequence]
- [consequence]

**Negative:**
- [consequence]
- [consequence]

**Neutral:**
- [consequence]
]

Step 2.3 -- File Naming

Name the file: NNNN-kebab-case-title.md

• NNNN is zero-padded to 4 digits
• Title is derived from the decision, converted to kebab-case
• Keep filename under 60 characters
• Example: 0003-use-postgresql-for-primary-datastore.md

============================================================ PHASE 3: RETROSPECTIVE MODE

When running in retrospective mode, analyze the codebase to infer architectural decisions that were made but never documented:

Step 3.1 -- Detect Decisions

Scan for these categories of decisions:

Category	What to Look For
Language/Runtime	Primary language, runtime version constraints
Framework	Web framework, UI framework, CLI framework choice
Database	Database type, ORM/query builder choice
Auth	Authentication strategy, provider choice
State Management	State management library/pattern
API Style	REST vs GraphQL vs gRPC, API versioning strategy
Infrastructure	Docker, K8s, serverless, cloud provider
CI/CD	Pipeline tool, deployment strategy
Testing	Test framework, testing strategy (unit/integration/e2e)
Monorepo vs Polyrepo	Repository structure decision
Dependency Management	Package manager, lockfile strategy
Code Style	Linter, formatter, style guide
Error Handling	Error handling strategy, logging approach
Caching	Caching strategy, cache provider

Step 3.2 -- Generate ADRs

For each detected decision:

1. Determine if an ADR already exists for this decision
2. If not, create one with status "accepted" and today's date
3. In the Context section, note that this is a retrospective ADR: "This ADR was created retrospectively to document a decision already in effect."
4. Infer context from the codebase (why this choice likely was made)
5. Document consequences based on how the choice has played out

Step 3.3 -- Prioritize

Generate retrospective ADRs in priority order:

1. Framework and language choices (highest architectural impact)
2. Database and data layer decisions
3. Authentication and security patterns
4. Infrastructure and deployment choices
5. Testing and code quality decisions

============================================================ PHASE 4: INDEX GENERATION

Generate or update docs/adr/README.md (or docs/adr/index.md):

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## What is an ADR?

An ADR is a short document that captures an important architectural decision
made along with its context and consequences.

## ADR Index

| # | Title | Status | Date |
|---|-------|--------|------|
| [0001](0001-title.md) | Title | Accepted | YYYY-MM-DD |
| [0002](0002-title.md) | Title | Superseded by [0003](0003-title.md) | YYYY-MM-DD |
| ... | ... | ... | ... |

## Statuses

- **Proposed** -- Under discussion, not yet decided
- **Accepted** -- Decision has been made and is in effect
- **Deprecated** -- Decision is no longer relevant
- **Superseded** -- Replaced by a newer decision (linked)

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing documentation, validate completeness:

1. Verify all required sections are present and non-empty.
2. Verify internal cross-references and links resolve correctly.
3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
4. Verify code examples are syntactically valid.

IF VALIDATION FAILS:

• Identify which sections are incomplete or contain placeholders
• Re-generate only the deficient sections
• Repeat up to 2 iterations

============================================================ OUTPUT

ADR Report

Action Taken

• Mode: [New ADR / Retrospective / Index / Supersede / Deprecate]
• ADRs Created: N
• ADRs Updated: N
• Total ADRs: N

ADR Summary

#	Title	Status	Date
NNNN	Title	Status	Date
...	...	...	...

Files Written

• docs/adr/NNNN-title.md -- [description]
• docs/adr/README.md -- Updated index

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /adr — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT

• Do NOT fabricate technical context. Only document decisions that are evident from the codebase.
• Do NOT create ADRs for trivial decisions (e.g., "use prettier for formatting" is too small; "adopt Prettier + ESLint with specific rule overrides" is worth documenting).
• Do NOT create duplicate ADRs for decisions already documented.
• Do NOT change the status of existing ADRs unless explicitly asked.
• Do NOT use ADR numbers that are already taken.
• Do NOT include opinions in the Context section -- state facts and forces.

NEXT STEPS:

After creating ADRs:

• "Run /document to check overall documentation health."
• "Run /diagram to generate architecture diagrams that complement these ADRs."
• "Run /arch-review to review the architecture decisions for consistency."