laurigates/adr-relationships

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

1. Domain Analysis: Scope ADRs by domain tag to find related decisions
2. Conflict Detection: Surface potential conflicts in same domain
3. Relationship Validation: Ensure bidirectional consistency
4. 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:

1. Scan docs/adrs/*.md for matching domain: field
2. For each match with status "Accepted", extract:
   • ADR number and title
   • Key decision outcome
3. 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