Conflict detection for contradicting decisions #5

New issue

Closed

opened 2026-01-21 20:45:25 +00:00 by jack · 0 comments

jack commented

2026-01-21 20:45:25 +00:00

Owner

Problem

Over time, architectural decisions are documented as observations. Later, one might:

Forget earlier decisions
Implement something that contradicts a previous choice
Not notice that a new pattern conflicts with established conventions

Solution

1. Decision Categories

Tag observations of type decision with categories:

type DecisionCategory =
  | 'architecture'      // System design, patterns
  | 'technology'        // Library/framework choices
  | 'convention'        // Code style, naming
  | 'security'          // Security policies
  | 'performance'       // Performance decisions
  | 'api'               // API design choices
  | 'database';         // Schema decisions

Database schema addition:

ALTER TABLE observations ADD COLUMN decision_category TEXT;
ALTER TABLE observations ADD COLUMN superseded_by INTEGER REFERENCES observations(id);
ALTER TABLE observations ADD COLUMN supersedes INTEGER REFERENCES observations(id);

2. Conflict Detection Algorithm

When a new decision observation is created:

Extract keywords from the new decision (using AI or keyword extraction)
Search existing decisions in the same category and project
Semantic similarity check using embeddings (if Qdrant enabled)
AI conflict analysis - compare potentially conflicting decisions

interface ConflictCheckResult {
  hasConflict: boolean;
  conflictingDecisions: Array<{
    observation: Observation;
    similarity: number;
    conflictType: 'contradicts' | 'supersedes' | 'related';
    explanation: string;
  }>;
}

3. Conflict Resolution Workflow

New Decision: "Use Redux for global state management"

⚠️ Potential Conflict Detected:
────────────────────────────────────────
Decision #1234 (2024-03-15):
"Use React Context for state - avoid external state libraries"

Options:
  [1] This supersedes the old decision (mark #1234 as superseded)
  [2] These are compatible (different scopes)
  [3] Cancel - rethink this decision

4. UI Integration

In WebUI:

Decision timeline view showing evolution
Conflict warnings on observation detail page
"Superseded" badge on outdated decisions
Decision graph visualization (optional)

In CLAUDE.md context:

## Active Decisions
- Use Redux for global state (supersedes #1234)
- API uses REST with OpenAPI spec
- ⚠️ Conflicting: JWT vs Session auth (unresolved)

5. API Endpoints

// Check for conflicts before saving
POST /api/observations/check-conflicts
Body: { content: string, type: 'decision', category: string, project: string }
Response: ConflictCheckResult

// Mark decision as superseded
POST /api/observations/:id/supersede
Body: { supersededBy: number, reason: string }

// Get decision history for a category
GET /api/projects/:project/decisions?category=architecture

Implementation Steps

Add database columns for decision tracking
Create DecisionService with conflict detection logic
Add embedding-based similarity search for decisions
Create AI prompt for conflict analysis
Add API endpoints
Add UI components for conflict resolution
Integrate into observation creation flow
Add to CLAUDE.md context generation

Files to Create/Modify

packages/database/src/entities/Observation.ts - Add columns
packages/backend/src/services/decision-service.ts - New service
packages/backend/src/routes/observations.ts - New endpoints
packages/worker/src/tasks/conflict-check.ts - AI conflict analysis
packages/ui/src/components/DecisionConflict.tsx - UI component
packages/types/src/decisions.ts - New types

Acceptance Criteria

Decisions can be categorized
Conflicts are detected on new decision creation
User can resolve conflicts (supersede/compatible/cancel)
Superseded decisions are marked and tracked
Decision history is visible in UI
Active decisions appear in CLAUDE.md context

Migrated-From: jack/claude-mem-fork#76

## Problem Over time, architectural decisions are documented as observations. Later, one might: - Forget earlier decisions - Implement something that contradicts a previous choice - Not notice that a new pattern conflicts with established conventions ## Solution ### 1. Decision Categories Tag observations of type `decision` with categories: ```typescript type DecisionCategory = | 'architecture' // System design, patterns | 'technology' // Library/framework choices | 'convention' // Code style, naming | 'security' // Security policies | 'performance' // Performance decisions | 'api' // API design choices | 'database'; // Schema decisions ``` **Database schema addition:** ```sql ALTER TABLE observations ADD COLUMN decision_category TEXT; ALTER TABLE observations ADD COLUMN superseded_by INTEGER REFERENCES observations(id); ALTER TABLE observations ADD COLUMN supersedes INTEGER REFERENCES observations(id); ``` ### 2. Conflict Detection Algorithm When a new `decision` observation is created: 1. **Extract keywords** from the new decision (using AI or keyword extraction) 2. **Search existing decisions** in the same category and project 3. **Semantic similarity check** using embeddings (if Qdrant enabled) 4. **AI conflict analysis** - compare potentially conflicting decisions ```typescript interface ConflictCheckResult { hasConflict: boolean; conflictingDecisions: Array<{ observation: Observation; similarity: number; conflictType: 'contradicts' | 'supersedes' | 'related'; explanation: string; }>; } ``` ### 3. Conflict Resolution Workflow ``` New Decision: "Use Redux for global state management" ⚠️ Potential Conflict Detected: ──────────────────────────────────────── Decision #1234 (2024-03-15): "Use React Context for state - avoid external state libraries" Options: [1] This supersedes the old decision (mark #1234 as superseded) [2] These are compatible (different scopes) [3] Cancel - rethink this decision ``` ### 4. UI Integration **In WebUI:** - Decision timeline view showing evolution - Conflict warnings on observation detail page - "Superseded" badge on outdated decisions - Decision graph visualization (optional) **In CLAUDE.md context:** ```markdown ## Active Decisions - Use Redux for global state (supersedes #1234) - API uses REST with OpenAPI spec - ⚠️ Conflicting: JWT vs Session auth (unresolved) ``` ### 5. API Endpoints ```typescript // Check for conflicts before saving POST /api/observations/check-conflicts Body: { content: string, type: 'decision', category: string, project: string } Response: ConflictCheckResult // Mark decision as superseded POST /api/observations/:id/supersede Body: { supersededBy: number, reason: string } // Get decision history for a category GET /api/projects/:project/decisions?category=architecture ``` ## Implementation Steps 1. [ ] Add database columns for decision tracking 2. [ ] Create `DecisionService` with conflict detection logic 3. [ ] Add embedding-based similarity search for decisions 4. [ ] Create AI prompt for conflict analysis 5. [ ] Add API endpoints 6. [ ] Add UI components for conflict resolution 7. [ ] Integrate into observation creation flow 8. [ ] Add to CLAUDE.md context generation ## Files to Create/Modify - `packages/database/src/entities/Observation.ts` - Add columns - `packages/backend/src/services/decision-service.ts` - New service - `packages/backend/src/routes/observations.ts` - New endpoints - `packages/worker/src/tasks/conflict-check.ts` - AI conflict analysis - `packages/ui/src/components/DecisionConflict.tsx` - UI component - `packages/types/src/decisions.ts` - New types ## Acceptance Criteria - [ ] Decisions can be categorized - [ ] Conflicts are detected on new decision creation - [ ] User can resolve conflicts (supersede/compatible/cancel) - [ ] Superseded decisions are marked and tracked - [ ] Decision history is visible in UI - [ ] Active decisions appear in CLAUDE.md context --- Migrated-From: jack/claude-mem-fork#76