ADR: Statistics and health metrics (adr_stats)

[rshade]

Priority: P2 - Medium Priority

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

Problem Statement

Teams need visibility into their ADR health - how many decisions exist, what's their status distribution, how often are decisions being made, and what patterns exist over time.

Proposed Solution

Implement adr_stats tool that:

1. Provides summary statistics
2. Shows status distribution
3. Analyzes decision patterns over time
4. Identifies potential issues (stale proposals, high churn)

Implementation Guidance

Tool Schema

const AdrStatsArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
});

Statistics Interface

interface AdrStats {
  total: number;
  byStatus: {
    proposed: number;
    accepted: number;
    rejected: number;
    deprecated: number;
    superseded: number;
  };
  byMonth: { [month: string]: number };  // "2025-01": 3
  formats: { [format: string]: number }; // "nygard": 10, "madr": 2
  avgDecisionTime?: number;  // days from proposed to accepted
  staleProposals: number;    // proposed > 30 days
  supersessionRate: number;  // % of decisions eventually superseded
  health: {
    score: number;           // 0-100
    issues: string[];        // ["5 stale proposals", "no recent decisions"]
  };
}

Health Score Calculation

const healthFactors = {
  staleProposals: -5 per proposal,
  recentActivity: +20 if decision in last 30 days,
  acceptanceRate: +30 if > 70% accepted,
  documentationQuality: +20 if all sections present,
  supersessionHealth: +10 if supersessions properly linked,
};

Development Steps

1. Codebase Analysis

   • Review project_status tool patterns
   • Consider visualization options

2. Implementation

   • Aggregate statistics from parsed ADRs
   • Calculate time-based metrics
   • Implement health scoring
   • Format output clearly

3. Testing Requirements

   • Test with various ADR sets
   • Test edge cases (empty, single ADR)
   • Test health score accuracy
   • Target: 85-90%+ coverage

4. Linting & Validation

   make lint
   make test
   make build

Acceptance Criteria

Feature Complete:

• All statistics calculated correctly
• Health score is meaningful
• Time-based analysis works
• Output is well-formatted

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

adr_stats({})
// Returns:
// {
//   total: 15,
//   byStatus: {
//     proposed: 2,
//     accepted: 10,
//     rejected: 1,
//     deprecated: 1,
//     superseded: 1
//   },
//   byMonth: {
//     "2024-11": 3,
//     "2024-12": 5,
//     "2025-01": 7
//   },
//   formats: { "nygard": 15 },
//   avgDecisionTime: 4.5,  // days
//   staleProposals: 1,
//   supersessionRate: 0.07,
//   health: {
//     score: 85,
//     issues: ["1 proposal pending > 30 days"]
//   }
// }

References

• Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
• Depends on: Phase 1 tools (parsing)
• Similar to: project_status tool