Architecture Decision Records: Documenting Technical Decisions at Scale

Architecture Decision Records (ADRs) capture the context, reasoning, and consequences of significant technical decisions. Understanding when to write ADRs, how to structure them effectively, and how to maintain them as living documentation is essential for sustainable architecture evolution.

ADR Purpose and Value

┌─────────────────────────────────────────────────────────────────────────┐
│                    ADR Lifecycle and Value                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Decision Point                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  Problem Identified → Options Analyzed → Decision Made          │   │
│  │        │                    │                   │                │   │
│  │        ▼                    ▼                   ▼                │   │
│  │    Context              Evaluation         Rationale            │   │
│  │    captured             documented         recorded             │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                    │                                    │
│                                    ▼                                    │
│  Living Documentation                                                   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                                                                  │   │
│  │  Onboarding          Architecture         Decision              │   │
│  │  Acceleration        Reviews              Reversal              │   │
│  │       │                  │                   │                   │   │
│  │  "Why is it         "Does this          "What was the          │   │
│  │   this way?"         fit?"               original context?"     │   │
│  │                                                                  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                    │                                    │
│                                    ▼                                    │
│  Evolution                                                              │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  Status: Proposed → Accepted → Deprecated → Superseded          │   │
│  │                          │           │            │              │   │
│  │                     In effect    Being      Replaced by         │   │
│  │                                 phased out   newer ADR          │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

When to Write ADRs

Decision Significance Matrix

// Framework for determining if a decision warrants an ADR
interface DecisionSignificance {
  criteria: SignificanceCriteria;
  score: number; // 0-10
  recommendation: 'required' | 'recommended' | 'optional' | 'not_needed';
}

interface SignificanceCriteria {
  // Impact dimensions
  reversibility: 'easy' | 'moderate' | 'difficult' | 'impossible';
  scope: 'component' | 'service' | 'domain' | 'system' | 'organization';
  stakeholders: number; // Teams/individuals affected
  costImplication: 'minimal' | 'moderate' | 'significant' | 'major';

  // Temporal dimensions
  longevity: 'temporary' | 'short_term' | 'medium_term' | 'long_term' | 'permanent';
  precedentSetting: boolean; // Will this decision be used as a pattern?

  // Risk dimensions
  novelty: 'proven' | 'established' | 'emerging' | 'experimental';
  controversy: 'consensus' | 'mild_disagreement' | 'significant_debate' | 'contentious';
}

function evaluateDecisionSignificance(criteria: SignificanceCriteria): DecisionSignificance {
  let score = 0;

  // Reversibility weight: 25%
  const reversibilityScores = { easy: 0, moderate: 1, difficult: 2, impossible: 3 };
  score += reversibilityScores[criteria.reversibility] * 2.5 / 3 * 10 * 0.25;

  // Scope weight: 20%
  const scopeScores = { component: 0, service: 1, domain: 2, system: 3, organization: 4 };
  score += scopeScores[criteria.scope] * 2.5 / 4 * 10 * 0.20;

  // Stakeholders weight: 15%
  score += Math.min(criteria.stakeholders / 10, 1) * 10 * 0.15;

  // Cost weight: 15%
  const costScores = { minimal: 0, moderate: 1, significant: 2, major: 3 };
  score += costScores[criteria.costImplication] * 2.5 / 3 * 10 * 0.15;

  // Longevity weight: 10%
  const longevityScores = { temporary: 0, short_term: 1, medium_term: 2, long_term: 3, permanent: 4 };
  score += longevityScores[criteria.longevity] * 2.5 / 4 * 10 * 0.10;

  // Novelty weight: 10%
  const noveltyScores = { proven: 0, established: 1, emerging: 2, experimental: 3 };
  score += noveltyScores[criteria.novelty] * 2.5 / 3 * 10 * 0.10;

  // Controversy weight: 5%
  const controversyScores = { consensus: 0, mild_disagreement: 1, significant_debate: 2, contentious: 3 };
  score += controversyScores[criteria.controversy] * 2.5 / 3 * 10 * 0.05;

  // Precedent bonus
  if (criteria.precedentSetting) {
    score += 1;
  }

  // Determine recommendation
  let recommendation: DecisionSignificance['recommendation'];
  if (score >= 7) {
    recommendation = 'required';
  } else if (score >= 5) {
    recommendation = 'recommended';
  } else if (score >= 3) {
    recommendation = 'optional';
  } else {
    recommendation = 'not_needed';
  }

  return { criteria, score, recommendation };
}

// Example decisions that warrant ADRs
const adrRequiredExamples = [
  'Choosing primary database technology',
  'Adopting a new programming language',
  'Selecting authentication/authorization approach',
  'Defining API versioning strategy',
  'Choosing microservices vs monolith',
  'Selecting cloud provider',
  'Establishing testing strategy',
  'Defining data retention policy',
];

// Example decisions that typically don't need ADRs
const adrNotNeededExamples = [
  'Upgrading a library patch version',
  'Fixing a bug',
  'Adding a new API endpoint following existing patterns',
  'Refactoring internal implementation',
  'Updating documentation',
];

ADR Structure and Templates

Comprehensive ADR Template

# ADR-{NUMBER}: {TITLE}

## Metadata
- **Status**: Proposed | Accepted | Deprecated | Superseded
- **Date**: YYYY-MM-DD
- **Decision Makers**: @person1, @person2
- **Consulted**: @person3, @person4
- **Informed**: Team-A, Team-B
- **Supersedes**: ADR-XXX (if applicable)
- **Superseded By**: ADR-YYY (if applicable)

## Context

### Problem Statement
{Clear, concise description of the problem or opportunity that necessitates a decision}

### Background
{Relevant history, previous decisions, or context that led to this point}

### Constraints
- {Constraint 1: e.g., "Must integrate with existing authentication system"}
- {Constraint 2: e.g., "Budget limited to $X/month"}
- {Constraint 3: e.g., "Team has no Rust expertise"}

### Assumptions
- {Assumption 1: e.g., "Traffic will grow 10x over next 2 years"}
- {Assumption 2: e.g., "Team size will double"}

## Decision Drivers
1. **{Driver 1}**: {Description and importance}
2. **{Driver 2}**: {Description and importance}
3. **{Driver 3}**: {Description and importance}

## Considered Options

### Option 1: {Name}
**Description**: {Brief description of the approach}

**Pros**:
- {Advantage 1}
- {Advantage 2}

**Cons**:
- {Disadvantage 1}
- {Disadvantage 2}

**Estimated Effort**: {T-shirt size or story points}

### Option 2: {Name}
{Same structure as Option 1}

### Option 3: {Name}
{Same structure as Option 1}

## Decision

We will implement **{Chosen Option}**.

### Rationale
{Explanation of why this option was chosen over others, explicitly addressing each decision driver}

### Trade-offs Accepted
- {Trade-off 1}: {Why acceptable}
- {Trade-off 2}: {Why acceptable}

## Consequences

### Positive
- {Benefit 1}
- {Benefit 2}

### Negative
- {Drawback 1 and mitigation strategy}
- {Drawback 2 and mitigation strategy}

### Neutral
- {Side effect that's neither positive nor negative}

## Implementation

### Action Items
- [ ] {Action 1} - Owner: @person - Due: YYYY-MM-DD
- [ ] {Action 2} - Owner: @person - Due: YYYY-MM-DD

### Validation Criteria
- {Criterion 1: How we'll know this decision was correct}
- {Criterion 2: Metrics to track}

### Rollback Plan
{Description of how to reverse this decision if needed}

## Related Decisions
- ADR-XXX: {Related decision and relationship}
- ADR-YYY: {Related decision and relationship}

## References
- {Link to design doc}
- {Link to RFC}
- {Link to external resource}

## Changelog
| Date | Author | Change |
|------|--------|--------|
| YYYY-MM-DD | @author | Initial draft |
| YYYY-MM-DD | @author | Updated based on feedback |

Lightweight ADR Template (Y-Statement)

# ADR-{NUMBER}: {TITLE}

**Status**: {Proposed | Accepted | Deprecated | Superseded}
**Date**: YYYY-MM-DD

## Decision

In the context of **{context}**,
facing **{concern}**,
we decided for **{decision}**
and against **{alternatives}**,
to achieve **{goal}**,
accepting **{trade-off}**.

## Consequences

{Bullet points of positive and negative consequences}

## Notes

{Any additional context or references}

ADR Management System

ADR Repository Structure

// ADR management and validation system
interface ADR {
  id: string;
  title: string;
  status: ADRStatus;
  createdAt: Date;
  updatedAt: Date;
  authors: string[];
  content: string;
  metadata: ADRMetadata;
  links: ADRLinks;
}

type ADRStatus = 'draft' | 'proposed' | 'accepted' | 'deprecated' | 'superseded' | 'rejected';

interface ADRMetadata {
  decisionMakers: string[];
  consulted: string[];
  informed: string[];
  tags: string[];
  domain: string;
  impactLevel: 'low' | 'medium' | 'high' | 'critical';
}

interface ADRLinks {
  supersedes?: string;
  supersededBy?: string;
  relatedTo: string[];
  implementations: string[]; // Links to PRs, issues, etc.
}

class ADRRepository {
  private adrs: Map<string, ADR> = new Map();
  private indexByStatus: Map<ADRStatus, Set<string>> = new Map();
  private indexByDomain: Map<string, Set<string>> = new Map();
  private indexByTag: Map<string, Set<string>> = new Map();

  // Create new ADR
  create(input: CreateADRInput): ADR {
    const id = this.generateId();

    const adr: ADR = {
      id,
      title: input.title,
      status: 'draft',
      createdAt: new Date(),
      updatedAt: new Date(),
      authors: input.authors,
      content: input.content,
      metadata: input.metadata,
      links: {
        relatedTo: [],
        implementations: []
      }
    };

    this.validate(adr);
    this.adrs.set(id, adr);
    this.updateIndexes(adr);

    return adr;
  }

  // Transition ADR status
  transitionStatus(id: string, newStatus: ADRStatus, reason?: string): ADR {
    const adr = this.adrs.get(id);
    if (!adr) throw new Error(`ADR ${id} not found`);

    // Validate transition
    this.validateTransition(adr.status, newStatus);

    // Remove from old status index
    this.indexByStatus.get(adr.status)?.delete(id);

    // Update status
    adr.status = newStatus;
    adr.updatedAt = new Date();

    // Add to new status index
    if (!this.indexByStatus.has(newStatus)) {
      this.indexByStatus.set(newStatus, new Set());
    }
    this.indexByStatus.get(newStatus)!.add(id);

    // Log transition
    this.logTransition(id, newStatus, reason);

    return adr;
  }

  // Supersede an ADR with a new one
  supersede(oldId: string, newId: string): void {
    const oldAdr = this.adrs.get(oldId);
    const newAdr = this.adrs.get(newId);

    if (!oldAdr || !newAdr) {
      throw new Error('Both ADRs must exist');
    }

    // Update links
    oldAdr.links.supersededBy = newId;
    newAdr.links.supersedes = oldId;

    // Transition old ADR to superseded
    this.transitionStatus(oldId, 'superseded', `Superseded by ${newId}`);
  }

  // Validate ADR structure and content
  private validate(adr: ADR): void {
    const errors: string[] = [];

    // Title validation
    if (!adr.title || adr.title.length < 10) {
      errors.push('Title must be at least 10 characters');
    }

    // Content sections validation
    const requiredSections = ['Context', 'Decision', 'Consequences'];
    for (const section of requiredSections) {
      if (!adr.content.includes(`## ${section}`)) {
        errors.push(`Missing required section: ${section}`);
      }
    }

    // Metadata validation
    if (adr.metadata.decisionMakers.length === 0) {
      errors.push('At least one decision maker is required');
    }

    if (errors.length > 0) {
      throw new ValidationError('ADR validation failed', errors);
    }
  }

  // Valid status transitions
  private validateTransition(from: ADRStatus, to: ADRStatus): void {
    const validTransitions: Record<ADRStatus, ADRStatus[]> = {
      draft: ['proposed', 'rejected'],
      proposed: ['accepted', 'rejected', 'draft'],
      accepted: ['deprecated', 'superseded'],
      deprecated: ['superseded'],
      superseded: [],
      rejected: ['draft']
    };

    if (!validTransitions[from].includes(to)) {
      throw new Error(`Invalid transition from ${from} to ${to}`);
    }
  }

  // Query ADRs
  query(filter: ADRFilter): ADR[] {
    let results = Array.from(this.adrs.values());

    if (filter.status) {
      const statusIds = this.indexByStatus.get(filter.status);
      if (statusIds) {
        results = results.filter(adr => statusIds.has(adr.id));
      } else {
        return [];
      }
    }

    if (filter.domain) {
      const domainIds = this.indexByDomain.get(filter.domain);
      if (domainIds) {
        results = results.filter(adr => domainIds.has(adr.id));
      } else {
        return [];
      }
    }

    if (filter.tags && filter.tags.length > 0) {
      results = results.filter(adr =>
        filter.tags!.some(tag => adr.metadata.tags.includes(tag))
      );
    }

    if (filter.search) {
      const searchLower = filter.search.toLowerCase();
      results = results.filter(adr =>
        adr.title.toLowerCase().includes(searchLower) ||
        adr.content.toLowerCase().includes(searchLower)
      );
    }

    // Sort by date descending
    results.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());

    return results;
  }

  // Generate ADR graph for visualization
  generateGraph(): ADRGraph {
    const nodes: GraphNode[] = [];
    const edges: GraphEdge[] = [];

    for (const adr of this.adrs.values()) {
      nodes.push({
        id: adr.id,
        label: adr.title,
        status: adr.status,
        domain: adr.metadata.domain
      });

      // Supersession edges
      if (adr.links.supersededBy) {
        edges.push({
          from: adr.id,
          to: adr.links.supersededBy,
          type: 'superseded_by'
        });
      }

      // Related edges
      for (const relatedId of adr.links.relatedTo) {
        edges.push({
          from: adr.id,
          to: relatedId,
          type: 'related_to'
        });
      }
    }

    return { nodes, edges };
  }

  private generateId(): string {
    const count = this.adrs.size + 1;
    return `ADR-${count.toString().padStart(4, '0')}`;
  }

  private updateIndexes(adr: ADR): void {
    // Status index
    if (!this.indexByStatus.has(adr.status)) {
      this.indexByStatus.set(adr.status, new Set());
    }
    this.indexByStatus.get(adr.status)!.add(adr.id);

    // Domain index
    if (!this.indexByDomain.has(adr.metadata.domain)) {
      this.indexByDomain.set(adr.metadata.domain, new Set());
    }
    this.indexByDomain.get(adr.metadata.domain)!.add(adr.id);

    // Tag indexes
    for (const tag of adr.metadata.tags) {
      if (!this.indexByTag.has(tag)) {
        this.indexByTag.set(tag, new Set());
      }
      this.indexByTag.get(tag)!.add(adr.id);
    }
  }

  private logTransition(id: string, status: ADRStatus, reason?: string): void {
    console.log(`ADR ${id} transitioned to ${status}${reason ? `: ${reason}` : ''}`);
  }
}

interface ADRFilter {
  status?: ADRStatus;
  domain?: string;
  tags?: string[];
  search?: string;
}

interface ADRGraph {
  nodes: GraphNode[];
  edges: GraphEdge[];
}

interface GraphNode {
  id: string;
  label: string;
  status: ADRStatus;
  domain: string;
}

interface GraphEdge {
  from: string;
  to: string;
  type: 'superseded_by' | 'related_to' | 'depends_on';
}

class ValidationError extends Error {
  constructor(message: string, public errors: string[]) {
    super(message);
  }
}

ADR Review Process

Review Workflow

// ADR review and approval workflow
interface ADRReview {
  adrId: string;
  reviewers: Reviewer[];
  status: ReviewStatus;
  comments: ReviewComment[];
  createdAt: Date;
  completedAt?: Date;
}

interface Reviewer {
  id: string;
  role: 'required' | 'optional';
  vote?: 'approve' | 'request_changes' | 'abstain';
  votedAt?: Date;
}

interface ReviewComment {
  id: string;
  authorId: string;
  content: string;
  section?: string; // Which section of the ADR
  lineNumber?: number;
  createdAt: Date;
  resolved: boolean;
  replies: ReviewComment[];
}

type ReviewStatus = 'pending' | 'in_review' | 'approved' | 'changes_requested' | 'rejected';

class ADRReviewWorkflow {
  private reviews: Map<string, ADRReview> = new Map();
  private adrRepo: ADRRepository;

  constructor(adrRepo: ADRRepository) {
    this.adrRepo = adrRepo;
  }

  // Initiate review for an ADR
  initiateReview(adrId: string, reviewerIds: string[]): ADRReview {
    // Determine required reviewers based on ADR metadata
    const adr = this.adrRepo.get(adrId);
    const requiredReviewers = this.determineRequiredReviewers(adr);

    const reviewers: Reviewer[] = [
      ...requiredReviewers.map(id => ({ id, role: 'required' as const })),
      ...reviewerIds
        .filter(id => !requiredReviewers.includes(id))
        .map(id => ({ id, role: 'optional' as const }))
    ];

    const review: ADRReview = {
      adrId,
      reviewers,
      status: 'pending',
      comments: [],
      createdAt: new Date()
    };

    this.reviews.set(adrId, review);

    // Transition ADR to proposed
    this.adrRepo.transitionStatus(adrId, 'proposed');

    // Notify reviewers
    this.notifyReviewers(review);

    return review;
  }

  // Submit a review vote
  submitVote(
    adrId: string,
    reviewerId: string,
    vote: Reviewer['vote'],
    comment?: string
  ): ADRReview {
    const review = this.reviews.get(adrId);
    if (!review) throw new Error(`No review found for ADR ${adrId}`);

    const reviewer = review.reviewers.find(r => r.id === reviewerId);
    if (!reviewer) throw new Error('Reviewer not found');

    reviewer.vote = vote;
    reviewer.votedAt = new Date();

    if (comment) {
      review.comments.push({
        id: crypto.randomUUID(),
        authorId: reviewerId,
        content: comment,
        createdAt: new Date(),
        resolved: false,
        replies: []
      });
    }

    // Update review status
    this.updateReviewStatus(review);

    return review;
  }

  // Check if review is complete and update status
  private updateReviewStatus(review: ADRReview): void {
    const requiredReviewers = review.reviewers.filter(r => r.role === 'required');
    const allRequiredVoted = requiredReviewers.every(r => r.vote !== undefined);

    if (!allRequiredVoted) {
      review.status = 'in_review';
      return;
    }

    // Check for any changes requested
    const changesRequested = review.reviewers.some(r => r.vote === 'request_changes');
    if (changesRequested) {
      review.status = 'changes_requested';
      return;
    }

    // Check for approval
    const requiredApprovals = requiredReviewers.filter(r => r.vote === 'approve');
    const approvalThreshold = Math.ceil(requiredReviewers.length * 0.5);

    if (requiredApprovals.length >= approvalThreshold) {
      review.status = 'approved';
      review.completedAt = new Date();

      // Transition ADR to accepted
      this.adrRepo.transitionStatus(review.adrId, 'accepted');
    }
  }

  // Determine required reviewers based on ADR impact and domain
  private determineRequiredReviewers(adr: ADR): string[] {
    const reviewers: string[] = [];

    // High impact decisions need architecture review
    if (adr.metadata.impactLevel === 'critical' || adr.metadata.impactLevel === 'high') {
      reviewers.push('architecture-board');
    }

    // Domain-specific reviewers
    const domainOwners = this.getDomainOwners(adr.metadata.domain);
    reviewers.push(...domainOwners);

    // Security-related decisions need security review
    if (adr.metadata.tags.includes('security')) {
      reviewers.push('security-team');
    }

    return [...new Set(reviewers)]; // Deduplicate
  }

  private getDomainOwners(domain: string): string[] {
    // Implementation would look up domain ownership
    const domainOwnerMap: Record<string, string[]> = {
      'authentication': ['auth-team-lead'],
      'data-platform': ['data-team-lead'],
      'api': ['api-team-lead'],
      'infrastructure': ['infra-team-lead'],
    };

    return domainOwnerMap[domain] || [];
  }

  private notifyReviewers(review: ADRReview): void {
    // Send notifications to reviewers
    for (const reviewer of review.reviewers) {
      console.log(`Notifying ${reviewer.id} about ADR review`);
    }
  }
}

ADR Maintenance and Governance

Periodic Review Process

// ADR health monitoring and maintenance
class ADRGovernance {
  private adrRepo: ADRRepository;
  private reviewPeriodMonths = 12;

  constructor(adrRepo: ADRRepository) {
    this.adrRepo = adrRepo;
  }

  // Identify ADRs that need review
  identifyStaleADRs(): StaleADRReport {
    const now = new Date();
    const staleThreshold = new Date();
    staleThreshold.setMonth(staleThreshold.getMonth() - this.reviewPeriodMonths);

    const acceptedADRs = this.adrRepo.query({ status: 'accepted' });
    const staleADRs: StaleADR[] = [];

    for (const adr of acceptedADRs) {
      // Check last review date
      if (adr.updatedAt < staleThreshold) {
        const staleness = this.calculateStaleness(adr, now);
        staleADRs.push({
          adr,
          daysSinceUpdate: staleness.days,
          priority: staleness.priority,
          reason: staleness.reason
        });
      }
    }

    // Sort by priority
    staleADRs.sort((a, b) => {
      const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
      return priorityOrder[a.priority] - priorityOrder[b.priority];
    });

    return {
      totalActive: acceptedADRs.length,
      staleCount: staleADRs.length,
      staleADRs,
      generatedAt: now
    };
  }

  // Calculate staleness and priority
  private calculateStaleness(adr: ADR, now: Date): Staleness {
    const daysSinceUpdate = Math.floor(
      (now.getTime() - adr.updatedAt.getTime()) / (1000 * 60 * 60 * 24)
    );

    let priority: 'low' | 'medium' | 'high' | 'critical';
    let reason: string;

    // High impact ADRs need more frequent review
    if (adr.metadata.impactLevel === 'critical') {
      if (daysSinceUpdate > 180) {
        priority = 'critical';
        reason = 'Critical ADR not reviewed in 6+ months';
      } else {
        priority = 'high';
        reason = 'Critical ADR approaching review deadline';
      }
    } else if (adr.metadata.impactLevel === 'high') {
      if (daysSinceUpdate > 365) {
        priority = 'high';
        reason = 'High-impact ADR not reviewed in 12+ months';
      } else {
        priority = 'medium';
        reason = 'High-impact ADR approaching review deadline';
      }
    } else {
      if (daysSinceUpdate > 548) { // 18 months
        priority = 'medium';
        reason = 'ADR significantly overdue for review';
      } else {
        priority = 'low';
        reason = 'ADR due for periodic review';
      }
    }

    return { days: daysSinceUpdate, priority, reason };
  }

  // Check for orphaned or conflicting ADRs
  validateADRConsistency(): ConsistencyReport {
    const issues: ConsistencyIssue[] = [];
    const allADRs = this.adrRepo.query({});

    // Check for broken links
    for (const adr of allADRs) {
      if (adr.links.supersedes) {
        const superseded = this.adrRepo.get(adr.links.supersedes);
        if (!superseded) {
          issues.push({
            adrId: adr.id,
            type: 'broken_link',
            severity: 'high',
            description: `Supersedes non-existent ADR: ${adr.links.supersedes}`
          });
        } else if (superseded.links.supersededBy !== adr.id) {
          issues.push({
            adrId: adr.id,
            type: 'inconsistent_link',
            severity: 'medium',
            description: `Supersession link not reciprocated`
          });
        }
      }

      for (const relatedId of adr.links.relatedTo) {
        const related = this.adrRepo.get(relatedId);
        if (!related) {
          issues.push({
            adrId: adr.id,
            type: 'broken_link',
            severity: 'low',
            description: `Related to non-existent ADR: ${relatedId}`
          });
        }
      }
    }

    // Check for contradicting decisions
    const acceptedADRs = allADRs.filter(a => a.status === 'accepted');
    for (let i = 0; i < acceptedADRs.length; i++) {
      for (let j = i + 1; j < acceptedADRs.length; j++) {
        if (this.mightConflict(acceptedADRs[i], acceptedADRs[j])) {
          issues.push({
            adrId: acceptedADRs[i].id,
            type: 'potential_conflict',
            severity: 'medium',
            description: `May conflict with ADR ${acceptedADRs[j].id} - same domain/tags`,
            relatedAdrId: acceptedADRs[j].id
          });
        }
      }
    }

    return {
      totalADRs: allADRs.length,
      issueCount: issues.length,
      issues,
      generatedAt: new Date()
    };
  }

  private mightConflict(adr1: ADR, adr2: ADR): boolean {
    // Same domain
    if (adr1.metadata.domain === adr2.metadata.domain) {
      // Check for overlapping tags that might indicate conflict
      const overlappingTags = adr1.metadata.tags.filter(t =>
        adr2.metadata.tags.includes(t)
      );
      return overlappingTags.length > 0;
    }
    return false;
  }
}

interface StaleADRReport {
  totalActive: number;
  staleCount: number;
  staleADRs: StaleADR[];
  generatedAt: Date;
}

interface StaleADR {
  adr: ADR;
  daysSinceUpdate: number;
  priority: 'low' | 'medium' | 'high' | 'critical';
  reason: string;
}

interface Staleness {
  days: number;
  priority: 'low' | 'medium' | 'high' | 'critical';
  reason: string;
}

interface ConsistencyReport {
  totalADRs: number;
  issueCount: number;
  issues: ConsistencyIssue[];
  generatedAt: Date;
}

interface ConsistencyIssue {
  adrId: string;
  type: 'broken_link' | 'inconsistent_link' | 'potential_conflict' | 'orphaned';
  severity: 'low' | 'medium' | 'high';
  description: string;
  relatedAdrId?: string;
}

Key Takeaways

1. Write ADRs for significant decisions - Irreversible, cross-cutting, or precedent-setting
2. Capture context thoroughly - Future readers need to understand constraints and assumptions
3. Document alternatives considered - Shows due diligence and aids future re-evaluation
4. Keep ADRs immutable - Supersede rather than modify; maintain decision history
5. Establish clear ownership - Every ADR needs identifiable decision makers
6. Review periodically - Technology and business context evolves
7. Link related decisions - Build a navigable decision graph
8. Automate governance - Use tooling to enforce templates and identify staleness