claude-code-workflow 7.2.29 → 7.2.30

package/.claude/skills/ccw-chain/phases/workflow-tdd-plan/phases/04-conflict-resolution.md

@@ -0,0 +1,426 @@
+# Phase 4: Conflict Resolution (Conditional)
+
+Detect and resolve conflicts with CLI analysis. This phase is **conditional** - only executes when `conflict_risk >= medium`.
+
+## Objective
+
+- Detect conflicts between planned changes and existing codebase
+- Detect module scenario uniqueness (functional overlaps)
+- Present conflicts to user with resolution strategies
+- Apply selected resolution strategies
+- Update planning-notes.md with conflict decisions
+
+## Trigger Condition
+
+Only execute when context-package.json indicates `conflict_risk` is "medium" or "high".
+If `conflict_risk` is "none" or "low", skip directly to Phase 5.
+
+## Conflict Categories
+
+| Category | Description |
+|----------|-------------|
+| **Architecture** | Incompatible design patterns, module structure changes |
+| **API** | Breaking contract changes, signature modifications |
+| **Data Model** | Schema modifications, type breaking changes |
+| **Dependency** | Version incompatibilities, setup conflicts |
+| **ModuleOverlap** | Functional overlap, scenario boundary ambiguity, duplicate responsibility |
+
+## Execution
+
+### Step 4.1: Validation
+
+```javascript
+// 1. Verify session directory exists
+const sessionDir = `.workflow/active/${sessionId}`;
+if (!file_exists(sessionDir)) {
+  throw new Error(`Session directory not found: ${sessionDir}`);
+}
+
+// 2. Load context-package.json
+const contextPackage = JSON.parse(Read(contextPath));
+
+// 3. Check conflict_risk (skip if none/low)
+const conflictRisk = contextPackage.conflict_detection?.risk_level || 'low';
+if (conflictRisk === 'none' || conflictRisk === 'low') {
+  console.log("No significant conflicts detected, proceeding to TDD task generation");
+  // Skip directly to Phase 5
+  return;
+}
+```
+
+### Step 4.2: CLI-Powered Conflict Analysis
+
+**Agent Delegation**:
+
+```javascript
+Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
+  ## Context
+  - Session: ${sessionId}
+  - Risk: ${conflictRisk}
+  - Files: ${existing_files_list}
+
+  ## Exploration Context (from context-package.exploration_results)
+  - Exploration Count: ${contextPackage.exploration_results?.exploration_count || 0}
+  - Angles Analyzed: ${JSON.stringify(contextPackage.exploration_results?.angles || [])}
+  - Pre-identified Conflict Indicators: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.conflict_indicators || [])}
+  - Critical Files: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.critical_files?.map(f => f.path) || [])}
+  - All Patterns: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_patterns || [])}
+  - All Integration Points: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_integration_points || [])}
+
+  ## Analysis Steps
+
+  ### 0. Load Output Schema (MANDATORY)
+  Execute: ccw tool exec json_builder '{"cmd":"info","schema":"conflict"}'
+
+  ### 1. Load Context
+  - Read existing files from conflict_detection.existing_files
+  - Load plan from .workflow/active/${sessionId}/.process/context-package.json
+  - Load exploration_results and use aggregated_insights for enhanced analysis
+  - Extract role analyses and requirements
+
+  ### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness)
+
+  Primary (Gemini):
+  ccw cli -p "
+  PURPOSE: Detect conflicts between plan and codebase, using exploration insights
+  TASK:
+  * Review pre-identified conflict_indicators from exploration results
+  * Compare architectures (use exploration key_patterns)
+  * Identify breaking API changes
+  * Detect data model incompatibilities
+  * Assess dependency conflicts
+  * Analyze module scenario uniqueness
+    - Use exploration integration_points for precise locations
+    - Cross-validate with exploration critical_files
+    - Generate clarification questions for boundary definition
+  MODE: analysis
+  CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/${sessionId}/**/*
+  EXPECTED: Conflict list with severity ratings, including:
+    - Validation of exploration conflict_indicators
+    - ModuleOverlap conflicts with overlap_analysis
+    - Targeted clarification questions
+  CONSTRAINTS: Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY
+  " --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root}
+
+  Fallback: Qwen (same prompt) -> Claude (manual analysis)
+
+  ### 3. Generate Strategies (2-4 per conflict)
+
+  Template per conflict:
+  - Severity: Critical/High/Medium
+  - Category: Architecture/API/Data/Dependency/ModuleOverlap
+  - Affected files + impact
+  - For ModuleOverlap: Include overlap_analysis with existing modules and scenarios
+  - Options with pros/cons, effort, risk
+  - For ModuleOverlap strategies: Add clarification_needed questions for boundary definition
+  - Recommended strategy + rationale
+
+  ### 4. Return Structured Conflict Data
+
+  Output to conflict-resolution.json (generated in Phase 4)
+
+  **Schema Reference**: Execute ccw tool exec json_builder '{"cmd":"info","schema":"conflict"}' to get schema summary
+
+  Return JSON following the schema. Key requirements:
+  - Minimum 2 strategies per conflict, max 4
+  - All text in Chinese for user-facing fields (brief, name, pros, cons, modification_suggestions)
+  - modifications.old_content: 20-100 chars for unique Edit tool matching
+  - modifications.new_content: preserves markdown formatting
+  - modification_suggestions: 2-5 actionable suggestions for custom handling
+
+  ### 5. Planning Notes Record (REQUIRED)
+  After analysis complete, append to planning-notes.md:
+
+  **File**: .workflow/active/${sessionId}/planning-notes.md
+  **Location**: Under "## Conflict Decisions (Phase 3)" section
+  **Format**:
+  ### [Conflict-Resolution Agent] YYYY-MM-DD
+  - **Note**: [Brief summary of conflict types, strategies, key decisions]
+`)
+```
+
+### Step 4.3: Iterative User Interaction
+
+```javascript
+const autoYes = workflowPreferences?.autoYes || false;
+
+FOR each conflict:
+  round = 0, clarified = false, userClarifications = []
+
+  WHILE (!clarified && round++ < 10):
+    // 1. Display conflict info (text output for context)
+    displayConflictSummary(conflict)  // id, brief, severity, overlap_analysis if ModuleOverlap
+
+    // 2. Strategy selection
+    if (autoYes) {
+      console.log(`[autoYes] Auto-selecting recommended strategy`)
+      selectedStrategy = conflict.strategies[conflict.recommended || 0]
+      clarified = true  // Skip clarification loop
+    } else {
+      AskUserQuestion({
+        questions: [{
+          question: formatStrategiesForDisplay(conflict.strategies),
+          header: "Strategy",
+          multiSelect: false,
+          options: [
+            ...conflict.strategies.map((s, i) => ({
+              label: `${s.name}${i === conflict.recommended ? ' (Recommended)' : ''}`,
+              description: `${s.complexity} complexity | ${s.risk} risk${s.clarification_needed?.length ? ' | Needs clarification' : ''}`
+            })),
+            { label: "Custom modification", description: `Suggestions: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` }
+          ]
+        }]
+      })
+
+      // 3. Handle selection
+      if (userChoice === "Custom modification") {
+        customConflicts.push({ id, brief, category, suggestions, overlap_analysis })
+        break
+      }
+
+      selectedStrategy = findStrategyByName(userChoice)
+    }
+
+    // 4. Clarification (if needed) - batched max 4 per call
+    if (!autoYes && selectedStrategy.clarification_needed?.length > 0) {
+      for (batch of chunk(selectedStrategy.clarification_needed, 4)) {
+        AskUserQuestion({
+          questions: batch.map((q, i) => ({
+            question: q, header: `Clarify${i+1}`, multiSelect: false,
+            options: [{ label: "Provide details", description: "Enter answer" }]
+          }))
+        })
+        userClarifications.push(...collectAnswers(batch))
+      }
+
+      // 5. Agent re-analysis
+      reanalysisResult = Agent({
+        subagent_type: "cli-execution-agent",
+        run_in_background: false,
+        prompt: `Conflict: ${conflict.id}, Strategy: ${selectedStrategy.name}
+User Clarifications: ${JSON.stringify(userClarifications)}
+Output: { uniqueness_confirmed, rationale, updated_strategy, remaining_questions }`
+      })
+
+      if (reanalysisResult.uniqueness_confirmed) {
+        selectedStrategy = { ...reanalysisResult.updated_strategy, clarifications: userClarifications }
+        clarified = true
+      } else {
+        selectedStrategy.clarification_needed = reanalysisResult.remaining_questions
+      }
+    } else {
+      clarified = true
+    }
+
+    if (clarified) resolvedConflicts.push({ conflict, strategy: selectedStrategy })
+  END WHILE
+END FOR
+
+selectedStrategies = resolvedConflicts.map(r => ({
+  conflict_id: r.conflict.id, strategy: r.strategy, clarifications: r.strategy.clarifications || []
+}))
+```
+
+### Step 4.4: Apply Modifications
+
+```javascript
+// 1. Extract modifications from resolved strategies
+const modifications = [];
+selectedStrategies.forEach(item => {
+  if (item.strategy && item.strategy.modifications) {
+    modifications.push(...item.strategy.modifications.map(mod => ({
+      ...mod,
+      conflict_id: item.conflict_id,
+      clarifications: item.clarifications
+    })));
+  }
+});
+
+console.log(`Applying ${modifications.length} modifications...`);
+
+// 2. Apply each modification using Edit tool (with fallback to context-package.json)
+const appliedModifications = [];
+const failedModifications = [];
+const fallbackConstraints = [];  // For files that don't exist
+
+modifications.forEach((mod, idx) => {
+  try {
+    console.log(`[${idx + 1}/${modifications.length}] Modifying ${mod.file}...`);
+
+    // Check if target file exists (brainstorm files may not exist in lite workflow)
+    if (!file_exists(mod.file)) {
+      console.log(`  File not found, writing to context-package.json as constraint`);
+      fallbackConstraints.push({
+        source: "conflict-resolution",
+        conflict_id: mod.conflict_id,
+        target_file: mod.file,
+        section: mod.section,
+        change_type: mod.change_type,
+        content: mod.new_content,
+        rationale: mod.rationale
+      });
+      return;  // Skip to next modification
+    }
+
+    if (mod.change_type === "update") {
+      Edit({ file_path: mod.file, old_string: mod.old_content, new_string: mod.new_content });
+    } else if (mod.change_type === "add") {
+      const fileContent = Read(mod.file);
+      const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content);
+      Write(mod.file, updated);
+    } else if (mod.change_type === "remove") {
+      Edit({ file_path: mod.file, old_string: mod.old_content, new_string: "" });
+    }
+
+    appliedModifications.push(mod);
+    console.log(`  Success`);
+  } catch (error) {
+    console.log(`  Failed: ${error.message}`);
+    failedModifications.push({ ...mod, error: error.message });
+  }
+});
+
+// 3. Generate conflict-resolution.json output file
+const resolutionOutput = {
+  session_id: sessionId,
+  resolved_at: new Date().toISOString(),
+  summary: {
+    total_conflicts: conflicts.length,
+    resolved_with_strategy: selectedStrategies.length,
+    custom_handling: customConflicts.length,
+    fallback_constraints: fallbackConstraints.length
+  },
+  resolved_conflicts: selectedStrategies.map(s => ({
+    conflict_id: s.conflict_id,
+    strategy_name: s.strategy.name,
+    strategy_approach: s.strategy.approach,
+    clarifications: s.clarifications || [],
+    modifications_applied: s.strategy.modifications?.filter(m =>
+      appliedModifications.some(am => am.conflict_id === s.conflict_id)
+    ) || []
+  })),
+  custom_conflicts: customConflicts.map(c => ({
+    id: c.id, brief: c.brief, category: c.category,
+    suggestions: c.suggestions, overlap_analysis: c.overlap_analysis || null
+  })),
+  planning_constraints: fallbackConstraints,
+  failed_modifications: failedModifications
+};
+
+const resolutionPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
+Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2));
+
+// 4. Update context-package.json with resolution details
+const contextPkg = JSON.parse(Read(contextPath));
+contextPkg.conflict_detection.conflict_risk = "resolved";
+contextPkg.conflict_detection.resolution_file = resolutionPath;
+contextPkg.conflict_detection.resolved_conflicts = selectedStrategies.map(s => s.conflict_id);
+contextPkg.conflict_detection.custom_conflicts = customConflicts.map(c => c.id);
+contextPkg.conflict_detection.resolved_at = new Date().toISOString();
+Write(contextPath, JSON.stringify(contextPkg, null, 2));
+
+// 5. Output custom conflict summary with overlap analysis (if any)
+if (customConflicts.length > 0) {
+  customConflicts.forEach(conflict => {
+    console.log(`[${conflict.category}] ${conflict.id}: ${conflict.brief}`);
+    if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) {
+      console.log(`Overlap info: New module: ${conflict.overlap_analysis.new_module.name}`);
+    }
+    conflict.suggestions.forEach(s => console.log(`  - ${s}`));
+  });
+}
+```
+
+### TodoWrite Update (Phase 4 in progress - tasks attached, if conflict_risk >= medium)
+
+```json
+[
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4: Conflict Resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
+  {"content": "  -> Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "  -> Present conflicts to user", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "  -> Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+### TodoWrite Update (Phase 4 completed - tasks collapsed)
+
+```json
+[
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4: Conflict Resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+### Step 4.5: Update Planning Notes
+
+After conflict resolution completes (if executed), update planning-notes.md:
+
+```javascript
+if (conflictRisk === 'medium' || conflictRisk === 'high') {
+  const conflictResPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
+
+  if (file_exists(conflictResPath)) {
+    const conflictRes = JSON.parse(Read(conflictResPath));
+    const resolved = conflictRes.resolved_conflicts || [];
+    const modifiedArtifacts = conflictRes.modified_artifacts || [];
+    const planningConstraints = conflictRes.planning_constraints || [];
+
+    // Update Phase 4 section
+    Edit(planningNotesPath, {
+      old: '## Conflict Decisions (Phase 4)\n(To be filled if conflicts detected)',
+      new: `## Conflict Decisions (Phase 4)
+
+- **RESOLVED**: ${resolved.map(r => `${r.type} -> ${r.strategy}`).join('; ') || 'None'}
+- **MODIFIED_ARTIFACTS**: ${modifiedArtifacts.join(', ') || 'None'}
+- **CONSTRAINTS**: ${planningConstraints.join('; ') || 'None'}`
+    })
+
+    // Append Phase 4 constraints to consolidated list
+    if (planningConstraints.length > 0) {
+      const currentNotes = Read(planningNotesPath);
+      const constraintCount = (currentNotes.match(/^\d+\./gm) || []).length;
+
+      Edit(planningNotesPath, {
+        old: '## Consolidated Constraints (Phase 5 Input)',
+        new: `## Consolidated Constraints (Phase 5 Input)
+${planningConstraints.map((c, i) => `${constraintCount + i + 1}. [Conflict] ${c}`).join('\n')}`
+      })
+    }
+  }
+}
+```
+
+**Auto-Continue**: Return to user showing conflict resolution results and selected strategies, then auto-continue.
+
+**Auto Mode**: When `workflowPreferences.autoYes` is true, conflict-resolution automatically applies recommended resolution strategies without user confirmation.
+
+### Step 4.6: Memory State Check
+
+Evaluate current context window usage and memory state:
+
+- If memory usage is high (>110K tokens or approaching context limits):
+
+```javascript
+Skill(skill="memory-capture")
+```
+
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
+## Output
+
+- **File**: `conflict-resolution.json` (if conflicts resolved)
+- **TodoWrite**: Mark Phase 4 completed, Phase 5 in_progress
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 5: TDD Task Generation](05-tdd-task-generation.md).