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
1---
2name: adr-relationships
3description: Domain analysis, conflict detection, and relationship validation for Architecture Decision Records. Use when creating or validating ADRs to ensure consistency.
4user-invocable: false
5allowed-tools: Bash, Read, Grep, Glob, TodoWrite
6created: 2026-01-15
7modified: 2026-04-25
8reviewed: 2026-04-25
9---
10
11# ADR Relationship Management
12
13Provides logic for domain analysis, conflict detection, and relationship tracking in Architecture Decision Records.
14
15## When to Use This Skill
16
17| Use this skill when... | Use blueprint-adr-validate instead when... |
18|---|---|
19| You need domain tagging logic for grouping related ADRs | You're running a one-shot ADR validation report |
20| You need conflict detection between ADRs in the same domain | You're auditing all ADRs before a release |
21| You need bidirectional relationship validation between ADRs | Use blueprint-adr-list instead when you only need a flat ADR index |
22| You're authoring a new ADR and want to find related decisions | Use blueprint-derive-plans instead when generating ADRs from existing code |
23
24## Core Capabilities
25
261. **Domain Analysis**: Scope ADRs by domain tag to find related decisions
272. **Conflict Detection**: Surface potential conflicts in same domain
283. **Relationship Validation**: Ensure bidirectional consistency
294. **Orphan Detection**: Find ADRs with broken references
30
31## Standard Domains
32
33| Domain | Covers |
34|--------|--------|
35| `state-management` | Redux, Zustand, MobX, Context, signals |
36| `data-layer` | Database choice, ORM, caching strategies |
37| `api-design` | REST, GraphQL, tRPC, versioning |
38| `authentication` | Auth providers, session handling, tokens |
39| `testing` | Test frameworks, strategies, coverage |
40| `deployment` | CI/CD, containers, serverless, hosting |
41| `frontend-framework` | React, Vue, Svelte, Angular |
42| `styling` | Tailwind, CSS-in-JS, SCSS, design tokens |
43| `build-tooling` | Bundlers, compilers, dev servers |
44| `monitoring` | Logging, metrics, error tracking |
45
46## Frontmatter Format
47
48```yaml
49---
50date: 2026-01-15
51status: Accepted | Superseded | Deprecated | Proposed
52domain: state-management
53supersedes: ADR-0003
54superseded-by: ADR-0012 # Set when superseded
55extends: ADR-0005
56related:
57 - ADR-0002
58 - ADR-0007
59---
60```
61
62## Conflict Detection Logic
63
64### Pre-Creation Analysis
65
66When creating a new ADR with a domain:
67
681. Scan `docs/adrs/*.md` for matching `domain:` field
692. For each match with status "Accepted", extract:
70 - ADR number and title
71 - Key decision outcome
723. Calculate conflict score
73
74### Conflict Scoring
75
76| Indicator | Weight | Description |
77|-----------|--------|-------------|
78| Same domain | +0.3 | Both decisions in same domain |
79| Both "Accepted" | +0.2 | Neither has been superseded |
80| Opposite outcomes | +0.4 | Decisions recommend different solutions |
81| Time gap > 6 months | +0.1 | Older decision may be stale |
82
83**Threshold**: Score >= 0.7 indicates potential conflict requiring user decision.
84
85### Relationship Types
86
87| Relationship | When to Use | Example |
88|--------------|-------------|---------|
89| `supersedes` | New decision replaces old | "Use Zustand" supersedes "Use Redux" |
90| `extends` | New decision builds on old | "Add persistence" extends "Use Zustand" |
91| `related` | Decisions are connected | "Use TypeScript" related to "Use Vite" |
92
93## Domain Inference
94
95Map discussion topics to domains:
96
97| Topic Keywords | Inferred Domain |
98|----------------|-----------------|
99| Redux, Zustand, MobX, useState, signals | `state-management` |
100| Prisma, Drizzle, PostgreSQL, MongoDB, ORM | `data-layer` |
101| REST, GraphQL, tRPC, OpenAPI, endpoints | `api-design` |
102| OAuth, JWT, auth0, session, tokens | `authentication` |
103| Vitest, Jest, Playwright, Cypress, coverage | `testing` |
104| Tailwind, styled-components, CSS modules | `styling` |
105| React, Vue, Svelte, Next.js, Nuxt | `frontend-framework` |
106| Vite, Webpack, esbuild, turbopack | `build-tooling` |
107| Docker, Kubernetes, Vercel, serverless | `deployment` |
108| Sentry, DataDog, logging, metrics | `monitoring` |
109
110## Validation Rules
111
112### Reference Integrity
113
114| Check | Validation |
115|-------|------------|
116| `supersedes` target exists | ADR file must exist |
117| `supersedes` target status | Must be "Superseded" with `superseded-by` set |
118| `extends` target exists | ADR file must exist |
119| `extends` target not superseded | Warning if extending outdated decision |
120| `related` targets exist | All referenced ADRs must exist |
121| No self-reference | ADR cannot reference itself |
122| No circular supersedes | A->B->A is invalid |
123
124### Bidirectional Consistency
125
126When ADR-A supersedes ADR-B:
127- ADR-A: `supersedes: ADR-B`
128- ADR-B: `superseded-by: ADR-A`, `status: Superseded`
129
130## Commands
131
132### Find ADRs by domain
133
134```bash
135grep -l "^domain: state-management" docs/adrs/*.md
136```
137
138### Extract ADR metadata
139
140```bash
141for f in docs/adrs/*.md; do
142 echo "=== $f ==="
143 head -20 "$f" | grep -E "^(date|status|domain|supersedes|extends|related):"
144done
145```
146
147### Find potential conflicts
148
149```bash
150# Count Accepted ADRs per domain
151grep -h "^domain:" docs/adrs/*.md | sort | uniq -c | while read count domain; do
152 if [ "$count" -gt 1 ]; then
153 echo "Potential conflict in $domain: $count Accepted ADRs"
154 fi
155done
156```
157
158### Validate references
159
160```bash
161# Check all supersedes references
162grep -h "^supersedes: ADR-" docs/adrs/*.md | cut -d' ' -f2 | while read ref; do
163 num="${ref#ADR-}"
164 ls docs/adrs/*-"$num"-*.md 2>/dev/null || echo "Missing: $ref"
165done
166```
167
168## Quick Reference
169
170| Operation | Pattern |
171|-----------|---------|
172| Find by domain | `grep -l "^domain: X" docs/adrs/*.md` |
173| List all domains | `grep -h "^domain:" docs/adrs/*.md \| sort -u` |
174| Find superseded | `grep -l "^status: Superseded" docs/adrs/*.md` |
175| Check references | Parse frontmatter, verify targets exist |
176| Detect conflicts | Multiple Accepted in same domain |
177
178## Integration Points
179
180- **`/blueprint:derive-plans`**: Pre-creation conflict analysis
181- **`/blueprint:adr-validate`**: Full validation report
182- **`/blueprint:status`**: ADR health summary
183- **document-detection skill**: Domain inference for auto-detected ADRs
laurigates