Claude-Code-Workflow/.claude/commands/workflow/tools/conflict-resolution.md

name, description, argument-hint, examples

name	description	argument-hint	examples
conflict-resolution	Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis	--session WFS-session-id --context path/to/context-package.json	/workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json

Conflict Resolution Command

Purpose

Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.

Scope: Detection and strategy generation only - NO code modification or task creation.

Trigger: Auto-executes in /workflow:plan Phase 3 when conflict_risk ≥ medium.

Core Responsibilities

Responsibility	Description
Detect Conflicts	Analyze plan vs existing code inconsistencies
Generate Strategies	Provide 2-4 resolution options per conflict
CLI Analysis	Use Gemini/Qwen (Claude fallback)
User Decision	Present options, never auto-apply
Single Output	CONFLICT_RESOLUTION.md with findings

Conflict Categories

1. Architecture Conflicts

• Incompatible design patterns
• Module structure changes
• Pattern migration requirements

2. API Conflicts

• Breaking contract changes
• Signature modifications
• Public interface impacts

3. Data Model Conflicts

• Schema modifications
• Type breaking changes
• Data migration needs

4. Dependency Conflicts

• Version incompatibilities
• Setup conflicts
• Breaking updates

Execution Flow

Phase 1: Validation

1. Verify session directory exists
2. Load context-package.json
3. Check conflict_risk (skip if none/low)
4. Prepare agent task prompt

Phase 2: CLI-Powered Analysis

Agent Delegation:

Task(subagent_type="cli-execution-agent", prompt=`
  ## Context
  - Session: {session_id}
  - Risk: {conflict_risk}
  - Files: {existing_files_list}

  ## Analysis Steps

  ### 1. Load Context
  - Read existing files from conflict_detection.existing_files
  - Load plan from .workflow/{session_id}/.process/context-package.json
  - Extract role analyses and requirements

  ### 2. Execute CLI Analysis

  Primary (Gemini):
  cd {project_root} && gemini -p "
  PURPOSE: Detect conflicts between plan and codebase
  TASK:
  • Compare architectures
  • Identify breaking API changes
  • Detect data model incompatibilities
  • Assess dependency conflicts
  MODE: analysis
  CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
  EXPECTED: Conflict list with severity ratings
  RULES: Focus on breaking changes and migration needs
  "

  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
  - Affected files + impact
  - Options with pros/cons, effort, risk
  - Recommended strategy + rationale

  ### 4. Return Structured Conflict Data

  ⚠️ DO NOT generate CONFLICT_RESOLUTION.md file

  Return JSON format for programmatic processing:

  \`\`\`json
  {
    "conflicts": [
      {
        "id": "CON-001",
        "brief": "一行中文冲突摘要",
        "severity": "Critical|High|Medium",
        "category": "Architecture|API|Data|Dependency",
        "affected_files": [
          ".workflow/{session}/.brainstorm/guidance-specification.md",
          ".workflow/{session}/.brainstorm/system-architect/analysis.md"
        ],
        "description": "详细描述冲突 - 什么不兼容",
        "impact": {
          "scope": "影响的模块/组件",
          "compatibility": "Yes|No|Partial",
          "migration_required": true|false,
          "estimated_effort": "人天估计"
        },
        "strategies": [
          {
            "name": "策略名称（中文）",
            "approach": "实现方法简述",
            "complexity": "Low|Medium|High",
            "risk": "Low|Medium|High",
            "effort": "时间估计",
            "pros": ["优点1", "优点2"],
            "cons": ["缺点1", "缺点2"],
            "modifications": [
              {
                "file": ".workflow/{session}/.brainstorm/guidance-specification.md",
                "section": "## 2. System Architect Decisions",
                "change_type": "update",
                "old_content": "原始内容片段（用于定位）",
                "new_content": "修改后的内容",
                "rationale": "为什么这样改"
              },
              {
                "file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
                "section": "## Design Decisions",
                "change_type": "update",
                "old_content": "原始内容片段",
                "new_content": "修改后的内容",
                "rationale": "修改理由"
              }
            ]
          },
          {
            "name": "策略2名称",
            "approach": "...",
            "complexity": "Medium",
            "risk": "Low",
            "effort": "1-2天",
            "pros": ["优点"],
            "cons": ["缺点"],
            "modifications": [...]
          }
        ],
        "recommended": 0
      }
    ],
    "summary": {
      "total": 2,
      "critical": 1,
      "high": 1,
      "medium": 0
    }
  }
  \`\`\`

  ⚠️ CRITICAL Requirements for modifications field:
  - old_content: Must be exact text from target file (20-100 chars for unique match)
  - new_content: Complete replacement text (maintains formatting)
  - change_type: "update" (replace), "add" (insert), "remove" (delete)
  - file: Full path relative to project root
  - section: Markdown heading for context (helps locate position)
  - Minimum 2 strategies per conflict, max 4
  - All text in Chinese for user-facing fields (brief, name, pros, cons)

  Quality Standards:
  - Each strategy must have actionable modifications
  - old_content must be precise enough for Edit tool matching
  - new_content preserves markdown formatting and structure
  - Recommended strategy (index) based on lowest complexity + risk
`)

Agent Internal Flow:

1. Load context package
2. Check conflict_risk (exit if none/low)
3. Read existing files + plan artifacts
4. Run CLI analysis (Gemini→Qwen→Claude)
5. Parse conflict findings
6. Generate 2-4 strategies per conflict with modifications
7. Return JSON to stdout (NOT file write)
8. Return execution log path

Phase 3: User Confirmation via AskUserQuestion

Command parses agent JSON output and presents conflicts to user:

// 1. Parse agent JSON output
const conflictData = JSON.parse(agentOutput);
const conflicts = conflictData.conflicts.slice(0, 4); // Max 4 (tool limit)

// 2. Build AskUserQuestion with all conflicts
const questions = conflicts.map((conflict, idx) => ({
  question: `${conflict.id}: ${conflict.brief} - 请选择解决方案`,
  header: `冲突${idx + 1}`,
  multiSelect: false,
  options: [
    ...conflict.strategies.map(s => ({
      label: s.name,
      description: `${s.approach} | 复杂度: ${s.complexity} | 风险: ${s.risk} | 工作量: ${s.effort}`
    })),
    {
      label: "跳过此冲突",
      description: "稍后手动处理，不应用任何修改"
    }
  ]
}));

// 3. Call AskUserQuestion
AskUserQuestion({questions});

// 4. Parse user selections
const selectedStrategies = parseUserAnswers(answers, conflicts);

User Selection Examples:

Question: "CON-001: 现有认证系统与计划不兼容 - 请选择解决方案"
Options:
  - "渐进式迁移" | 复杂度: Medium | 风险: Low | 工作量: 3-5天
  - "完全重写" | 复杂度: High | 风险: Medium | 工作量: 7-10天
  - "跳过此冲突"

Phase 4: Apply Modifications

// 1. Extract modifications from selected strategies
const modifications = [];
selectedStrategies.forEach(strategy => {
  if (strategy !== "skip") {
    modifications.push(...strategy.modifications);
  }
});

// 2. Apply each modification using Edit tool
modifications.forEach(mod => {
  if (mod.change_type === "update") {
    Edit({
      file_path: mod.file,
      old_string: mod.old_content,
      new_string: mod.new_content
    });
  }
  // Handle "add" and "remove" similarly
});

// 3. Update context-package.json
const contextPackage = JSON.parse(Read(contextPath));
contextPackage.conflict_detection.conflict_risk = "resolved";
contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
contextPackage.conflict_detection.resolved_at = new Date().toISOString();
Write(contextPath, JSON.stringify(contextPackage, null, 2));

// 4. Return summary
return {
  resolved: modifications.length,
  skipped: selectedStrategies.filter(s => s === "skip").length,
  modified_files: [...new Set(modifications.map(m => m.file))]
};

Validation:

✓ Agent returns valid JSON structure
✓ AskUserQuestion displays all conflicts (max 4)
✓ User selections captured correctly
✓ Edit tool successfully applies modifications
✓ guidance-specification.md updated
✓ Role analyses (*.md) updated
✓ context-package.json marked as resolved
✓ Agent log saved to .workflow/{session_id}/.chat/

Output Format: Agent JSON Response

Focus: Structured conflict data with actionable modifications for programmatic processing.

Format: JSON to stdout (NO file generation)

Structure: Defined in Phase 2, Step 4 (agent prompt)

Key Requirements

Requirement	Details
Conflict limit	Max 4 conflicts (AskUserQuestion tool limit)
Strategy count	2-4 strategies per conflict
Modifications	Each strategy includes file paths, old_content, new_content
User-facing text	Chinese (brief, strategy names, pros/cons)
Technical fields	English (severity, category, complexity, risk)
old_content precision	20-100 chars for unique Edit tool matching
File targets	guidance-specification.md, role analyses (*.md)

Error Handling

Recovery Strategy

1. Pre-check: Verify conflict_risk ≥ medium
2. Monitor: Track agent via Task tool
3. Validate: Parse agent JSON output
4. Recover:
   - Agent failure → check logs + report error
   - Invalid JSON → retry once with Claude fallback
   - CLI failure → fallback to Claude analysis
   - Edit tool failure → report affected files + rollback option
   - User cancels → mark as "unresolved", continue to task-generate
5. Degrade: If all fail, generate minimal conflict report and skip modifications

Rollback Handling

If Edit tool fails mid-application:
1. Log all successfully applied modifications
2. Offer rollback option via AskUserQuestion
3. If rollback selected: restore files from git or backups
4. If continue: mark partial resolution in context-package.json

Integration

Interface

Input:

• --session (required): WFS-{session-id}
• --context (required): context-package.json path
• Requires: conflict_risk ≥ medium

Output:

• Modified files:
  • .workflow/{session_id}/.brainstorm/guidance-specification.md
  • .workflow/{session_id}/.brainstorm/{role}/analysis.md
  • .workflow/{session_id}/.process/context-package.json (conflict_risk → resolved)
• NO report file generation

User Interaction:

• AskUserQuestion for strategy selection (max 4 conflicts)
• Each conflict: 2-4 strategy options + "跳过" option

Success Criteria

✓ CLI analysis returns valid JSON structure
✓ Max 4 conflicts presented (tool limit)
✓ Min 2 strategies per conflict with modifications
✓ AskUserQuestion displays all conflicts correctly
✓ User selections captured and processed
✓ Edit tool applies modifications successfully
✓ guidance-specification.md updated with resolved conflicts
✓ Role analyses (*.md) updated with resolved conflicts
✓ context-package.json marked as "resolved"
✓ No CONFLICT_RESOLUTION.md file generated
✓ Modification summary returned to user
✓ Agent log saved to .workflow/{session_id}/.chat/
✓ Error handling robust (validate/retry/degrade)

Related Commands

Command	Relationship
/workflow:tools:context-gather	Generates input conflict_detection data
/workflow:plan	Auto-triggers this when risk ≥ medium
/workflow:tools:task-generate	Uses resolved conflicts from updated brainstorm files
/workflow:brainstorm:artifacts	Generates guidance-specification.md (modified by this command)