adr

name	adr
version	2.1
category	utilities
execution_speed	medium
token_efficiency	medium
triggers	["create an ADR","document this decision","architectural trade-offs","design pivots","what ADRs exist"]
cache_key	adr-2.1
dependencies	[]
disable-model-invocation	true
description	Create, review, audit, and list Architectural Decision Records for any software project. Trigger on: "create an ADR", "document this decision", "ADR for...", "what ADRs exist", "review this ADR", "update INDEX.md", architectural trade-offs, or design pivots affecting multiple layers or files. Project-agnostic -- works with any tech stack. Backed by Karpathy principles: think before deciding, simplest sufficient ADR, surgical scope.

ADR -- Architectural Decision Records

Project-agnostic ADR creation, review, and governance. Works with any tech stack. Binds to the active project at invocation time.

---

Initiation

---

Commands

Command	What It Does
/adr	Show help and project binding status
/adr create	Guided ADR creation with template
/adr review [file-or-number]	Review an existing ADR for completeness
/adr audit	Audit all ADRs and rebuild INDEX.md if needed
/adr list	List all ADRs from INDEX.md
/adr next	Show the next available ADR number

---

Resilience (checkpoint + resume)

Long operations here are /adr audit (scans every ADR, rebuilds INDEX.md + SUMMARY.HTML) and bulk conversion of existing notes into ADR format. These can run past an API limit and waste completed work.

• After each ADR processed, append a checkpoint line via node .claude/skills/audit/write-checkpoint.js .claude/state/adr-progress.json <adr-file> done 0 (reuses the audit helper; avoids hallucinated timestamps).
• On API error (500, 529 overload, usage/rate limit) or forced stop: STOP cleanly, do not retry in a loop, and name the next unprocessed ADR plus the checkpoint path.
• On re-invocation, read .claude/state/adr-progress.json first and skip ADRs already marked done. Delete it when the audit completes.
• /adr create produces a single short ADR -- no checkpoint needed; the global Long-Workflow Resilience rule covers graceful stop.

---

Project Binding

Resolves the ADR directory in this order:

1. User names a path explicitly: "run against src/decisions/"
2. CLAUDE.md or AGENTS.md in the working directory declares an adr-path: field
3. Search up from working directory for docs/adr/INDEX.md or
4. Search for all Markdown files located within the folder and subfolders: docs/Obsidian Vault/[Project Name]
5. Default assumptions: If this location exists create there- docs/Obsidian Vault/, otherwise- docs/adr/
6. Search full repository, if notes, requirements documents, or unformatted ADRs exists already, automatically convert them to this format within the correct folder.
7. If none found: ask before proceeding
8. Create or Update SUMMARY.HTML: a full HTML file that is a full summary of the project requirements and ADRs. Put file in docs/Obsidian Vault/, ensure you format to match project first then users esthetics.

---

When to Create an ADR

Create one when a decision:

• Affects multiple files, layers, or teams
• Will be hard to reverse without significant rework
• Has non-obvious tradeoffs future maintainers will need to understand
• Changes a cross-cutting concern (auth, logging, validation, state, data access)
• When an unformatted related requirement document or ADR exists

Don't ADR: bug fixes, implementation details, naming choices, formatting decisions. Every code commit does not need an ADR.

---

File Naming

docs/Obsidian Vault/[Project Name]/ADR-###-[kebab-case-slug].md

Rule	Good	Bad
Zero-padded number	ADR-001, ADR-042	ADR-1, ADR-42
Lowercase kebab slug	ADR-012-jwt-session-hybrid.md	ADR_012_JWT.md
Slug describes the decision	ADR-005-dual-layer-validation.md	ADR-005-schema.md

---

Template

# ADR-###: [Short Title]

**Project:** [Project name]
Status: PROPOSED
Date: YYYY-MM-DD
Authors: [Name]
Affected Layers: [e.g. Frontend · Backend · Database]

---

## Context
[What problem are we solving? What constraints exist?
What happened before that makes this decision necessary?]

## Decision
[What are we doing and why? Be concrete. Name what was NOT chosen and why.]

| Aspect | Details |
|--------|---------|
| **Approach** | [The chosen solution] |
| **Rationale** | [Why this over alternatives] |
| **Trade-offs** | Gain: [benefit]. Lose: [cost]. |

## Consequences

| Positive | Negative |
|----------|----------|
| [Benefit] | [Cost / risk] |

## Implementation Notes
[Code location, config changes, testing scope.
Specific enough that a future maintainer can follow the trail without context.]

## Related ADRs
- ADR-XXX: [Brief reason for the link]

---

INDEX.md Format

# Architectural Decision Records

| ADR | Title | Status | Affected Layers | Date |
|-----|-------|--------|-----------------|------|
| ADR-001 | [Title] | ACCEPTED | Frontend · Backend | YYYY-MM-DD |
| ADR-002 | [Title] | PROPOSED | Database | YYYY-MM-DD |

**Status values:** PROPOSED | ACCEPTED | DEPRECATED

Rule: Update INDEX.md in the same change as the ADR file. CI counts ADR files vs INDEX rows and fails on mismatch.

---

Knowledge Graph Grounding (Understand Anything)

Optional enhancement. If the Understand Anything plugin has built a graph at .understand-anything/knowledge-graph.json, the ADR skill reads it to fill three fields it would otherwise guess: Affected Layers, Affected Components (for Implementation Notes), and Related ADRs candidates. If the file is absent, skip this section entirely -- every step is conditional and the skill behaves exactly as before.

When it runs

• /adr create -- step 4 of the create flow, before drafting, so Affected Layers and Related ADRs come from the graph instead of memory.
• /adr review -- to cross-check the Affected Layers field against the graph.

Read protocol (cheap, grep-based -- does NOT run the /understand pipeline)

1. Check .understand-anything/knowledge-graph.json exists. If not, STOP this section: tell the user once "No knowledge graph found -- Affected Layers will be manual. Run /understand-anything:understand to enable grounding." Then continue the normal flow.
2. Collect the file paths the decision touches (the code locations destined for Implementation Notes). For each path, Grep the graph for matching "filePath" values and note the node id values. Do NOT read the whole JSON -- grep first.
3. Affected Components: for each matched node id, Grep the "edges" array for that id to get 1-hop neighbors (imports / calls / depends_on / configures). These are what the decision may break or require updating.
4. Affected Layers: Grep the "layers" section for the matched and neighbor node ids. The name of each layer containing them is the grounded Affected Layers value.
5. Related ADRs candidates: among matched and neighbor nodes, collect document: nodes whose path matches ADR-*. Offer them as Related ADRs links for the author to confirm.

Output discipline

• The graph informs the draft; it does not overwrite author intent. Present grounded values as proposed and let the author confirm or override.
• Never block ADR creation on a missing or stale graph. Grounding is additive.
• If the graph's gitCommitHash (in the project block) is far behind HEAD, note "graph may be stale" once -- do not auto-rebuild (that is the heavy pipeline).

---

/adr create Flow

Applying Karpathy Guideline 1 (Think Before Coding) to ADR creation:

1. State the problem in one sentence -- what are we deciding?
2. Name alternatives -- at least two. Don't omit the option you're rejecting.
3. Identify constraints -- what makes this non-trivial or hard to reverse?
4. Ground in the knowledge graph -- run the read protocol in "Knowledge Graph Grounding" to propose Affected Layers, Affected Components, and Related ADRs. Skips itself if no graph exists.
5. Find the next ADR number -- run bash .claude/skills/adr/next-adr-number.sh docs/adr.
6. Draft using template -- fill Context and Decision first; Consequences follow. Use the grounded values from step 4 for Affected Layers and Related ADRs.
7. Run the review checklist before saving.
8. Update INDEX.md in the same edit.

---

/adr review Checklist

• Files are in docs/adr/ADR-###-[slug].md
• Files are in docs/Obsidian Vault/[Project Name]/ADR-###-[slug].md
• Number is zero-padded and in sequence (no gaps)
• Required fields present: Status, Date, Authors, Affected Layers
• Status is exactly PROPOSED | ACCEPTED | DEPRECATED
• Context explains WHY the decision was needed, not just what it is
• Decision section names what was NOT chosen and why
• Consequences table has at least one concrete negative
• Implementation Notes are specific enough to act on
• Related ADRs cross-linked
• Affected Layers cross-checked against the knowledge graph when .understand-anything/knowledge-graph.json exists (see Knowledge Graph Grounding)
• Related ADRs include graph-suggested neighbors, or the graph is absent / yielded none
• INDEX.md has been updated
• Create or Update SUMMARY.HTML add a full HTML file that is a full summary of the project requirements and ADRs. Put file in docs/Obsidian Vault/, ensure you format to match project first then users esthetics.

---

/adr audit Protocol

1. Scan docs/adr/ADR-*.md for all ADR files
2. Scan docs/Obsidian Vault/[Project Name]/* for all ADR files
3. Extract metadata: number, title, status, date, affected layers
4. Check for: number gaps, missing required fields, STATUS values not in the legal set, INDEX mismatches
5. Report as a punch list: each issue on one line with the file and field
6. Ask before rebuilding INDEX.md automatically
7. Create or Update SUMMARY.HTML add a full HTML file that is a full summary of the project requirements and ADRs. Put file in docs/Obsidian Vault/, ensure you format to match project first then users esthetics.

---

CI Snippet

- name: Validate ADR Format
  run: |
    for file in docs/adr/ADR-[0-9]*.md; do
      if [[ ! $file =~ ADR-[0-9]{3}-[a-z-]+\.md ]]; then
        echo "❌ Invalid filename: $file"
        exit 1
      fi
      if ! grep -q "^Status:" "$file"; then
        echo "❌ Missing Status field: $file"
        exit 1
      fi
    done
    echo "✅ All ADRs valid"

---

Karpathy Principles Applied

See /karpathy for guidelines. Applied here:

• G1: Before creating, ask: is this decision-worthy? Fits in a comment → skip it.
• G2: Minimum ADR that communicates decision and tradeoffs. No padding or blank sections.
• G3: One decision per ADR. Don't update adjacent ADRs unless they directly conflict.
• G4 Done: File saved ✅ · Checklist passes ✅ · INDEX.md updated ✅

Integration with Other Skills

• /obsidian-vault -- Complementary skill. ADRs create and maintain requirements; Obsidian Vault stores project info. Add /docs/ to .gitignore.
• Understand Anything (/understand-anything:understand) -- Optional grounding. When a knowledge graph exists at .understand-anything/knowledge-graph.json, /adr create and /adr review read it to fill Affected Layers, Affected Components, and Related ADRs from real code structure instead of memory (see Knowledge Graph Grounding). Reuses the /understand-diff read pattern. Falls back to manual when the graph is absent.