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