Living ADR

Keep your architecture decisions documented and alive. Paste a git diff, a PR description, or just describe what you decided — and get a formatted, numbered ADR file ready to commit. When a new decision supersedes an old one, the old ADR gets automatically updated.

No templates to fill in. No formats to remember. Works from diffs, PRs, or plain English.

Trigger Phrases

• "write ADR", "create ADR", "new architecture decision"
• "document this decision", "we decided to use X instead of Y"
• "architecture decision record", "why did we choose X"
• "update ADR", "this supersedes ADR-012"
• "/living-adr"

How to Provide Input

# Option 1: Describe the decision in plain English
/living-adr We're switching from REST to GraphQL for the user-facing API because
REST was causing over-fetching and the mobile team needed flexible queries.

# Option 2: Paste a git diff
/living-adr
[paste git diff here]

# Option 3: Paste a PR title + description
/living-adr
PR: "Replace JWT with session cookies for auth"
Description: JWTs were causing issues with token revocation...

# Option 4: Point to current changes
/living-adr --from-diff HEAD~1
/living-adr --from-pr 142

# Option 5: Explicitly supersede an existing ADR
/living-adr --supersedes ADR-008
We're moving from PostgreSQL to CockroachDB for global distribution...

Step 1: Discover Existing ADRs

Before creating a new ADR, inventory what already exists:

# Find the ADR directory (check common locations)
find . -type d -name "adr" 2>/dev/null | grep -v node_modules | head -5
find . -type d -name "decisions" 2>/dev/null | grep -v node_modules | head -5
find . -path "*/docs/adr*" -type f 2>/dev/null | grep -v node_modules | head -20

# If no ADR directory exists, create it
mkdir -p docs/adr

Parse all existing ADRs to build a registry:

# List all ADRs with their numbers, titles, and status
ls -1 docs/adr/*.md 2>/dev/null | while read f; do
  num=$(grep -m1 "^# ADR-" "$f" 2>/dev/null | grep -oE "ADR-[0-9]+" | head -1)
  title=$(grep -m1 "^# " "$f" 2>/dev/null | sed 's/^# //')
  status=$(grep -i "^## Status" -A1 "$f" 2>/dev/null | tail -1 | tr -d ' ')
  echo "$f | $num | $status | $title"
done

Registry output example:

docs/adr/ADR-001-use-postgresql.md | ADR-001 | Accepted | Use PostgreSQL as primary database
docs/adr/ADR-005-jwt-auth.md | ADR-005 | Accepted | Use JWT for API authentication
docs/adr/ADR-010-monorepo.md | ADR-010 | Deprecated | Use monorepo structure

Determine the next ADR number: max(existing numbers) + 1.

Step 2: Detect Architectural Signals (from diff or description)

When input is a git diff, scan for these architectural change patterns:

Database / Schema Changes

# New migration files = new DB decision
git diff --name-only HEAD~1 | grep -iE "migration|schema|alembic|flyway|prisma/migrations"

# New table, DROP TABLE, ALTER TABLE = schema evolution
git diff HEAD~1 | grep -iE "^+.*(CREATE TABLE|DROP TABLE|ADD COLUMN|ALTER TABLE)" | head -10

New External Integrations

# New dependencies in package.json / requirements.txt / go.mod
git diff HEAD~1 -- package.json requirements.txt go.mod Cargo.toml | grep "^+" | grep -v "^+++" | head -20

# New import of external SDK/client
git diff HEAD~1 | grep "^+.*import" | grep -iE "(stripe|twilio|sendgrid|aws|gcp|openai|anthropic)" | head -10

Auth / Security Pattern Changes

git diff HEAD~1 | grep -iE "(jwt|session|oauth|saml|ldap|auth0|cognito|firebase.auth)" | grep "^+" | head -10

Framework / Architecture Pattern Changes

# New config files suggesting framework adoption
git diff --name-only HEAD~1 | grep -iE "(next\.config|vite\.config|webpack\.config|docker-compose|k8s|helm/)"

# New top-level directories suggesting architectural restructure
git diff --name-only HEAD~1 | grep "^[^/]*/$" | head -10

From the signals detected, classify the decision type:

Step 3: Check for Supersession

Before creating a new ADR, check if it contradicts an existing one:

# Extract keywords from the new decision
# Then search existing ADRs for related content
grep -rl "PostgreSQL\|database\|Postgres" docs/adr/ 2>/dev/null
grep -rl "JWT\|auth\|token" docs/adr/ 2>/dev/null

If a related existing ADR is found:

• If the new decision replaces it → mark existing as Superseded by ADR-NNN
• If the new decision extends it → reference it in the new ADR's "Context" section
• If they coexist → note both in "Related ADRs"

Step 4: Draft the ADR

Use the Nygard format (the industry standard, used by ThoughtWorks, GitHub, Spotify):

# ADR-[NNN]: [Short imperative title — what was decided]

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by [ADR-NNN]
**Deciders:** [team/person who made this decision]
**Tags:** [database, auth, api, infrastructure, ...]

---

## Context

[What situation forced this decision? What constraints existed?
What problem were we trying to solve? 2-4 sentences max.]

## Decision

[The actual decision, stated clearly. "We will use X." or "We decided to Y."
One paragraph. No hedging.]

## Consequences

### Positive
- [benefit 1]
- [benefit 2]

### Negative / Trade-offs
- [drawback or cost 1]
- [known limitation]

### Neutral
- [things that are neither good nor bad, just different]

## Alternatives Considered

| Option | Why Rejected |
|--------|-------------|
| [Alt 1] | [reason] |
| [Alt 2] | [reason] |

## Related ADRs

- [ADR-NNN]: [relationship] — e.g., "Supersedes ADR-005 (JWT Auth)"
- [ADR-NNN]: [relationship] — e.g., "Related to ADR-002 (Database Choice)"

## References

- [Link to relevant docs, RFCs, blog posts, or issue tracker tickets]

Step 5: Write the File

# Determine next ADR number
NEXT_NUM=$(ls docs/adr/ADR-*.md 2>/dev/null | grep -oE "ADR-[0-9]+" | grep -oE "[0-9]+" | sort -n | tail -1)
NEXT_NUM=$(printf "%03d" $((${NEXT_NUM:-0} + 1)))

# Slugify the title
SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')

# Write the file
cat > "docs/adr/ADR-${NEXT_NUM}-${SLUG}.md" << 'EOF'
[generated ADR content]
EOF

echo "Created: docs/adr/ADR-${NEXT_NUM}-${SLUG}.md"

If superseding an existing ADR, update it:

# Add supersession notice to the old ADR
OLD_ADR="docs/adr/ADR-005-jwt-auth.md"
sed -i '' "s/^**Status:** Accepted/**Status:** Superseded by ADR-${NEXT_NUM}/" "$OLD_ADR"
echo "" >> "$OLD_ADR"
echo "> **Superseded:** This decision was replaced by [ADR-${NEXT_NUM}](ADR-${NEXT_NUM}-${SLUG}.md) on $(date +%Y-%m-%d)." >> "$OLD_ADR"

Output Format

After creating the ADR, report:

## ADR Created: ADR-NNN

**File:** `docs/adr/ADR-NNN-use-graphql-for-user-api.md`
**Status:** Proposed (ready for team review)

### What was detected
- Signal: `src/api/graphql/` directory created, `graphql` added to package.json
- Category: API Design
- Supersedes: ADR-003 (REST API Design) — that ADR has been marked "Superseded"

### ADR Summary
- **Decision:** Switch user-facing API from REST to GraphQL
- **Why:** Mobile team reported 3x over-fetching; query flexibility needed
- **Trade-offs:** GraphQL learning curve; N+1 query risk without DataLoader

### Next Steps
1. Review draft: `docs/adr/ADR-NNN-use-graphql-for-user-api.md`
2. Change status from `Proposed` → `Accepted` when team agrees
3. Commit both files: the new ADR + updated ADR-003

### Git command

git add docs/adr/ADR-NNN-use-graphql-for-user-api.md docs/adr/ADR-003-rest-api-design.md

git commit -m "docs(adr): ADR-NNN — use GraphQL for user-facing API"

ADR Status Lifecycle

Proposed → Accepted → Deprecated
                    ↘ Superseded by ADR-NNN

ADR Index Generation

After creating or updating ADRs, optionally regenerate the index:

# Generate docs/adr/README.md index
echo "# Architecture Decision Records" > docs/adr/README.md
echo "" >> docs/adr/README.md
echo "| ADR | Title | Status | Date |" >> docs/adr/README.md
echo "|-----|-------|--------|------|" >> docs/adr/README.md

ls -1 docs/adr/ADR-*.md 2>/dev/null | sort | while read f; do
  num=$(grep -m1 "^# ADR-" "$f" | grep -oE "ADR-[0-9]+")
  title=$(grep -m1 "^# ADR-" "$f" | sed "s/^# ADR-[0-9]*: //")
  status=$(grep -m1 "^\*\*Status:\*\*" "$f" | sed 's/\*\*Status:\*\* //')
  date=$(grep -m1 "^\*\*Date:\*\*" "$f" | sed 's/\*\*Date:\*\* //')
  fname=$(basename "$f")
  echo "| [$num]($fname) | $title | $status | $date |" >> docs/adr/README.md
done
echo "Generated docs/adr/README.md"

Quick Mode

For a fast, minimal ADR when you just want to record a decision:

/living-adr --quick "We're using Redis for session storage because the DB was getting hit too hard."

→ Creates ADR-NNN-use-redis-for-session-storage.md
   with pre-filled Context, Decision, and a placeholder Consequences section.
   Status: Proposed. Edit the file to add alternatives and sign off.

Why "Living" ADRs

Most ADR tools generate the file and stop. The "living" part means:

1. Auto-detection — no need to remember to write an ADR; the skill detects architectural signals in your diff
2. Supersession tracking — when you migrate from A to B, the skill finds the A-related ADR and marks it Superseded, keeping history clean
3. Index maintenance — the docs/adr/README.md index stays current
4. Committed alongside code — the git commit command is included in the output so the decision and the code change travel together in history

The goal: six months later, a new team member can run ls docs/adr/ and understand every significant architectural choice the team made, why they made it, and what replaced what.

Author

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041