Skip to content

ADR: Impact analysis for code changes (adr_impact) #300

@rshade

Description

@rshade

Priority: P2 - Medium Priority

Part of Epic: #289
Estimated Effort: 8-10 hours
Phase: 3 - AI-Assisted Features

Problem Statement

Code changes may conflict with or violate existing architectural decisions. Without automated checking, these conflicts go unnoticed until they cause problems. Proactive impact analysis helps maintain architectural integrity.

Proposed Solution

Implement adr_impact tool that:

  1. Analyzes code changes (git diff) against existing ADRs
  2. Identifies potential conflicts with accepted decisions
  3. Suggests relevant ADRs to reference in PRs
  4. Integrates with code_review for comprehensive feedback

Implementation Guidance

Tool Schema

const AdrImpactArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
  diff: z.string().optional()
    .describe("Git diff to analyze (default: staged changes)"),
  files: z.array(z.string()).optional()
    .describe("Specific files to check"),
  base: z.string().optional()
    .describe("Base branch for comparison (default: main)"),
});

Impact Result Interface

interface AdrImpactResult {
  conflicts: AdrConflict[];
  related: AdrMetadata[];
  suggestions: string[];
  prAnnotation: string;  // Ready-to-use PR description section
}

interface AdrConflict {
  adr: AdrMetadata;
  severity: 'high' | 'medium' | 'low';
  reason: string;
  evidence: string;      // Code snippet or file path
  resolution: string;    // Suggested action
}

Conflict Detection Patterns

Technology Conflicts:

// ADR-5 says "Use PostgreSQL"
// Diff adds: import { MongoClient } from 'mongodb'
// → Conflict: "Adding MongoDB conflicts with ADR-5 database decision"

Pattern Violations:

// ADR-8 says "Use repository pattern for data access"
// Diff adds: direct SQL query in service layer
// → Conflict: "Direct DB access violates ADR-8 repository pattern"

Dependency Changes:

// ADR-3 says "Use Express for HTTP"
// package.json adds: fastify
// → Warning: "Adding Fastify may conflict with ADR-3 Express decision"

Integration with code_review

// In git-tools.ts code_review
const impact = await adrTools.impact({ base });
if (impact.conflicts.length > 0) {
  review.concerns.push({
    category: 'architecture',
    severity: 'high',
    message: `Potential ADR conflicts: ${impact.conflicts.map(c => c.reason).join(', ')}`
  });
}

Development Steps

  1. Codebase Analysis

    • Review code_review patterns in src/tools/git-tools.ts
    • Understand diff parsing
  2. Implementation

    • Implement diff analysis
    • Build conflict detection rules
    • Integrate with ADR content matching
    • Generate PR-ready annotations
  3. Testing Requirements

    • Test various conflict scenarios
    • Test false positive rate
    • Test integration with code_review
    • Target: 85-90%+ coverage
  4. Linting & Validation

    make lint
    make test
    make build

Acceptance Criteria

Feature Complete:

  • Analyzes git diff for ADR conflicts
  • Detects technology/pattern violations
  • Generates actionable conflict reports
  • Integrates with code_review tool
  • Produces PR-ready annotation text

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

// Check staged changes
adr_impact({})
// Returns:
// {
//   conflicts: [
//     {
//       adr: { number: 5, title: "Use PostgreSQL" },
//       severity: 'high',
//       reason: "Adding MongoDB driver conflicts with database decision",
//       evidence: "package.json: +\"mongodb\": \"^6.0.0\"",
//       resolution: "Consider updating ADR-5 or removing MongoDB dependency"
//     }
//   ],
//   related: [
//     { number: 3, title: "Caching Strategy" }
//   ],
//   suggestions: [
//     "If changing database, create a new ADR that supersedes ADR-5",
//     "Consider discussing with the team before proceeding"
//   ],
//   prAnnotation: "## ADR Impact\n\n⚠️ **Potential Conflict:** This PR may..."
// }

// Check specific branch
adr_impact({ base: "develop" })

// Check specific files
adr_impact({ files: ["src/database/", "package.json"] })

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    adrArchitecture Decision Records toolingaiAI and machine learning featuresenhancementNew feature or requestpriority-mediumMedium priority issues

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions