ADR: Decision relationship graph (adr_graph)

[rshade]

Priority: P2 - Medium Priority

Part of Epic: #289
Estimated Effort: 6-8 hours
Phase: 2 - Analysis & Validation

Problem Statement

Understanding relationships between architectural decisions is crucial - which decisions supersede others, which are related, and how decisions have evolved over time. A visual graph helps teams understand the decision landscape.

Proposed Solution

Implement adr_graph tool that:

1. Generates decision relationship graphs
2. Shows supersession chains
3. Supports multiple output formats (Mermaid, DOT, text)
4. Optionally includes deprecated/superseded decisions

Implementation Guidance

Tool Schema

const AdrGraphArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
  format: z.enum(["mermaid", "dot", "text"]).optional()
    .describe("Graph output format (default: mermaid)"),
  includeDeprecated: z.boolean().optional()
    .describe("Include deprecated/superseded ADRs (default: false)"),
});

Graph Types

Supersession Graph:

graph TD
    ADR1[ADR-1: Use PostgreSQL]
    ADR5[ADR-5: Use MongoDB]
    ADR1 -->|superseded by| ADR5

Loading

Status-based grouping:

graph TD
    subgraph Accepted
        ADR2[Database Choice]
        ADR3[Caching Strategy]
    end
    subgraph Proposed
        ADR4[API Versioning]
    end

Loading

Output Formats

Mermaid (default):

graph TD
    ADR1["1. Use ADRs"] --> ADR2["2. Use PostgreSQL"]
    ADR2 -->|superseded| ADR5["5. Use MongoDB"]

DOT (Graphviz):

digraph ADRs {
    "ADR-1" -> "ADR-2"
    "ADR-2" -> "ADR-5" [label="superseded"]
}

Text:

ADR-1: Use ADRs (Accepted)
├── ADR-2: Use PostgreSQL (Superseded by ADR-5)
└── ADR-3: Use Redis (Accepted)
    └── ADR-5: Use MongoDB (Accepted, supersedes ADR-2)

Development Steps

1. Codebase Analysis

   • Review graph generation patterns
   • Consider Mermaid for GitHub rendering

2. Implementation

   • Build relationship graph from parsed ADRs
   • Implement format generators
   • Handle disconnected subgraphs
   • Color/style by status

3. Testing Requirements

   • Test with various relationship patterns
   • Test all output formats
   • Test with no relationships (all independent)
   • Target: 85-90%+ coverage

4. Linting & Validation

   make lint
   make test
   make build

Acceptance Criteria

Feature Complete:

• Generates supersession relationships
• All output formats work
• Handles deprecated/superseded filtering
• Renders in GitHub markdown (Mermaid)

Quality Gates:

• make lint passes with zero errors
• make test passes with 85-90%+ coverage
• make build completes successfully

Documentation:

• JSDoc comments for all public methods
• Update src/instructions.md

Example Usage

// Mermaid output (for GitHub)
adr_graph({ format: "mermaid" })
// Returns:
// ```mermaid
// graph TD
//     ADR1["1. Use ADRs"]
//     ADR2["2. Use PostgreSQL"]
//     ADR5["5. Use MongoDB"]
//     ADR2 -->|superseded by| ADR5
// ```

// Include all decisions
adr_graph({ includeDeprecated: true, format: "text" })

// DOT format for Graphviz
adr_graph({ format: "dot" })

References

• Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
• Depends on: Phase 1 tools (parsing)
• Mermaid docs: https://mermaid.js.org/
• Graphviz DOT: https://graphviz.org/doc/info/lang.html