-
Notifications
You must be signed in to change notification settings - Fork 1
Open
Labels
adrArchitecture Decision Records toolingArchitecture Decision Records toolingaiAI and machine learning featuresAI and machine learning featuresenhancementNew feature or requestNew feature or requestpriority-mediumMedium priority issuesMedium priority issues
Description
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:
- Analyzes code changes (git diff) against existing ADRs
- Identifies potential conflicts with accepted decisions
- Suggests relevant ADRs to reference in PRs
- 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
-
Codebase Analysis
- Review
code_reviewpatterns insrc/tools/git-tools.ts - Understand diff parsing
- Review
-
Implementation
- Implement diff analysis
- Build conflict detection rules
- Integrate with ADR content matching
- Generate PR-ready annotations
-
Testing Requirements
- Test various conflict scenarios
- Test false positive rate
- Test integration with code_review
- Target: 85-90%+ coverage
-
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 lintpasses with zero errors -
make testpasses with 85-90%+ coverage -
make buildcompletes 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
- Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
- Depends on: adr_search, adr_suggest
- Integrates with:
code_reviewinsrc/tools/git-tools.ts - Most advanced AI feature - key differentiator
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
adrArchitecture Decision Records toolingArchitecture Decision Records toolingaiAI and machine learning featuresAI and machine learning featuresenhancementNew feature or requestNew feature or requestpriority-mediumMedium priority issuesMedium priority issues