ADR Relationship Management

Provides logic for domain analysis, conflict detection, and relationship tracking in Architecture Decision Records.

When to Use This Skill

Use this skill when...	Use blueprint-adr-validate instead when...
You need domain tagging logic for grouping related ADRs	You're running a one-shot ADR validation report
You need conflict detection between ADRs in the same domain	You're auditing all ADRs before a release
You need bidirectional relationship validation between ADRs	Use blueprint-adr-list instead when you only need a flat ADR index
You're authoring a new ADR and want to find related decisions	Use blueprint-derive-plans instead when generating ADRs from existing code

Core Capabilities

Domain Analysis: Scope ADRs by domain tag to find related decisions
Conflict Detection: Surface potential conflicts in same domain
Relationship Validation: Ensure bidirectional consistency
Orphan Detection: Find ADRs with broken references

Standard Domains

Domain	Covers
`state-management`	Redux, Zustand, MobX, Context, signals
`data-layer`	Database choice, ORM, caching strategies
`api-design`	REST, GraphQL, tRPC, versioning
`authentication`	Auth providers, session handling, tokens
`testing`	Test frameworks, strategies, coverage
`deployment`	CI/CD, containers, serverless, hosting
`frontend-framework`	React, Vue, Svelte, Angular
`styling`	Tailwind, CSS-in-JS, SCSS, design tokens
`build-tooling`	Bundlers, compilers, dev servers
`monitoring`	Logging, metrics, error tracking

Frontmatter Format

---
date: 2026-01-15
status: Accepted | Superseded | Deprecated | Proposed
domain: state-management
supersedes: ADR-0003
superseded-by: ADR-0012    # Set when superseded
extends: ADR-0005
related:
  - ADR-0002
  - ADR-0007
---

Conflict Detection Logic

Pre-Creation Analysis

When creating a new ADR with a domain:

Scan docs/adrs/*.md for matching domain: field
For each match with status "Accepted", extract:
- ADR number and title
- Key decision outcome
Calculate conflict score

Conflict Scoring

Indicator	Weight	Description
Same domain	+0.3	Both decisions in same domain
Both "Accepted"	+0.2	Neither has been superseded
Opposite outcomes	+0.4	Decisions recommend different solutions
Time gap > 6 months	+0.1	Older decision may be stale

Threshold: Score >= 0.7 indicates potential conflict requiring user decision.

Relationship Types

Relationship	When to Use	Example
`supersedes`	New decision replaces old	"Use Zustand" supersedes "Use Redux"
`extends`	New decision builds on old	"Add persistence" extends "Use Zustand"
`related`	Decisions are connected	"Use TypeScript" related to "Use Vite"

Domain Inference

Map discussion topics to domains:

Topic Keywords	Inferred Domain
Redux, Zustand, MobX, useState, signals	`state-management`
Prisma, Drizzle, PostgreSQL, MongoDB, ORM	`data-layer`
REST, GraphQL, tRPC, OpenAPI, endpoints	`api-design`
OAuth, JWT, auth0, session, tokens	`authentication`
Vitest, Jest, Playwright, Cypress, coverage	`testing`
Tailwind, styled-components, CSS modules	`styling`
React, Vue, Svelte, Next.js, Nuxt	`frontend-framework`
Vite, Webpack, esbuild, turbopack	`build-tooling`
Docker, Kubernetes, Vercel, serverless	`deployment`
Sentry, DataDog, logging, metrics	`monitoring`

Validation Rules

Reference Integrity

Check	Validation
`supersedes` target exists	ADR file must exist
`supersedes` target status	Must be "Superseded" with `superseded-by` set
`extends` target exists	ADR file must exist
`extends` target not superseded	Warning if extending outdated decision
`related` targets exist	All referenced ADRs must exist
No self-reference	ADR cannot reference itself
No circular supersedes	A->B->A is invalid

Bidirectional Consistency

When ADR-A supersedes ADR-B:

ADR-A: supersedes: ADR-B
ADR-B: superseded-by: ADR-A, status: Superseded

Commands

Find ADRs by domain

grep -l "^domain: state-management" docs/adrs/*.md

Extract ADR metadata

for f in docs/adrs/*.md; do
  echo "=== $f ==="
  head -20 "$f" | grep -E "^(date|status|domain|supersedes|extends|related):"
done

Find potential conflicts

# Count Accepted ADRs per domain
grep -h "^domain:" docs/adrs/*.md | sort | uniq -c | while read count domain; do
  if [ "$count" -gt 1 ]; then
    echo "Potential conflict in $domain: $count Accepted ADRs"
  fi
done

Validate references

# Check all supersedes references
grep -h "^supersedes: ADR-" docs/adrs/*.md | cut -d' ' -f2 | while read ref; do
  num="${ref#ADR-}"
  ls docs/adrs/*-"$num"-*.md 2>/dev/null || echo "Missing: $ref"
done

Quick Reference

Operation	Pattern
Find by domain	`grep -l "^domain: X" docs/adrs/*.md`
List all domains	`grep -h "^domain:" docs/adrs/*.md \| sort -u`
Find superseded	`grep -l "^status: Superseded" docs/adrs/*.md`
Check references	Parse frontmatter, verify targets exist
Detect conflicts	Multiple Accepted in same domain

Integration Points

/blueprint:derive-plans: Pre-creation conflict analysis
/blueprint:adr-validate: Full validation report
/blueprint:status: ADR health summary
document-detection skill: Domain inference for auto-detected ADRs

adr-relationships