feat: Implement multi-phase project analysis workflow with Mermaid diagram generation and CPCC compliance documentation

- Phase 3: Added Mermaid diagram generation for system architecture, function modules, algorithms, class diagrams, sequence diagrams, and error flows. - Phase 4: Assembled analysis and diagrams into a structured CPCC-compliant document with section templates and figure numbering. - Phase 5: Developed compliance review process with iterative refinement based on analysis findings and user feedback. - Added CPCC compliance requirements and quality standards for project analysis reports. - Established a comprehensive project analysis skill with detailed execution flow and report types. - Enhanced error handling and recovery mechanisms throughout the analysis phases.
2026-02-14 02:42:04 +08:00 · 2025-12-26 11:44:29 +08:00
parent f14c3299bc
commit 89f6ac6804
25 changed files with 5018 additions and 34 deletions
--- a/.claude/skills/project-analyze/SKILL.md
+++ b/.claude/skills/project-analyze/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: project-analyze
+description: Multi-phase iterative project analysis with Mermaid diagrams. Generates architecture reports, design reports, method analysis reports. Use when analyzing codebases, understanding project structure, reviewing architecture, exploring design patterns, or documenting system components. Triggers on "analyze project", "architecture report", "design analysis", "code structure", "system overview".
+allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write
+---
+
+# Project Analysis Skill
+
+Generate comprehensive project analysis reports through multi-phase iterative workflow.
+
+## Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Phase 1: Requirements Discovery                                │
+│  → Read: phases/01-requirements-discovery.md                    │
+│  → Collect: report type, depth level, scope                     │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 2: Project Exploration                                   │
+│  → Read: phases/02-project-exploration.md                       │
+│  → Launch: parallel cli-explore-agents                          │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 3: Deep Analysis                                         │
+│  → Read: phases/03-deep-analysis.md                             │
+│  → Execute: Gemini CLI with exploration context                 │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 3.5: Diagram Generation                                  │
+│  → Read: phases/03.5-diagram-generation.md                      │
+│  → Reference: ../_shared/mermaid-utils.md                       │
+│  → Generate: Mermaid diagrams based on report type              │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 4: Report Generation                                     │
+│  → Read: phases/04-report-generation.md                         │
+│  → Reference: specs/quality-standards.md (Report Requirements)  │
+│  → Assemble: Markdown report with embedded diagrams             │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 5: Iterative Refinement                                  │
+│  → Read: phases/05-iterative-refinement.md                      │
+│  → Reference: specs/quality-standards.md (Quality Gates)        │
+│  → Validate: run quality checks before each iteration           │
+│  → Loop: discovery-driven questions until all gates pass        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Report Types
+
+| Type | Output | Focus |
+|------|--------|-------|
+| `architecture` | ARCHITECTURE-REPORT.md | System structure, modules, dependencies |
+| `design` | DESIGN-REPORT.md | Patterns, classes, interfaces |
+| `methods` | METHODS-REPORT.md | Algorithms, critical paths, APIs |
+| `comprehensive` | COMPREHENSIVE-REPORT.md | All above combined |
+
+## Directory Setup
+
+```bash
+timestamp=$(date +%Y%m%d-%H%M%S)
+dir=".workflow/.scratchpad/analyze-$timestamp"
+mkdir -p "$dir/diagrams" "$dir/iterations"
+echo "$dir"
+```
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | User interaction, config collection |
+| [phases/02-project-exploration.md](phases/02-project-exploration.md) | Parallel agent exploration |
+| [phases/03-deep-analysis.md](phases/03-deep-analysis.md) | Gemini CLI analysis |
+| [phases/03.5-diagram-generation.md](phases/03.5-diagram-generation.md) | Mermaid diagram generation |
+| [phases/04-report-generation.md](phases/04-report-generation.md) | Report assembly |
+| [phases/05-iterative-refinement.md](phases/05-iterative-refinement.md) | Discovery-driven refinement |
+| [specs/quality-standards.md](specs/quality-standards.md) | Quality gates, error handling |
+| [../_shared/mermaid-utils.md](../_shared/mermaid-utils.md) | Shared Mermaid utilities |
+
+## Output Structure
+
+```
+.workflow/.scratchpad/analyze-{timestamp}/
+├── analysis-config.json
+├── exploration-*.json
+├── deep-analysis.json
+├── diagrams/
+│   ├── manifest.json
+│   ├── validation.json
+│   └── *.mmd
+├── {TYPE}-REPORT.md
+└── iterations/
+```
--- a/.claude/skills/project-analyze/phases/01-requirements-discovery.md
+++ b/.claude/skills/project-analyze/phases/01-requirements-discovery.md
@@ -0,0 +1,79 @@
+# Phase 1: Requirements Discovery
+
+Collect user requirements before analysis begins.
+
+## Execution
+
+### Step 1: Report Type Selection
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "What type of project analysis report would you like?",
+    header: "Report Type",
+    multiSelect: false,
+    options: [
+      {label: "Architecture (Recommended)", description: "System structure, module relationships, layer analysis, dependency graph"},
+      {label: "Design", description: "Design patterns, class relationships, component interactions, abstraction analysis"},
+      {label: "Methods", description: "Key algorithms, critical code paths, core function explanations with examples"},
+      {label: "Comprehensive", description: "All above combined into a complete project analysis"}
+    ]
+  }]
+})
+```
+
+### Step 2: Depth Level Selection
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "What depth level do you need?",
+    header: "Depth",
+    multiSelect: false,
+    options: [
+      {label: "Overview", description: "High-level understanding, suitable for onboarding"},
+      {label: "Detailed", description: "In-depth analysis with code examples"},
+      {label: "Deep-Dive", description: "Exhaustive analysis with implementation details"}
+    ]
+  }]
+})
+```
+
+### Step 3: Scope Definition
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "What scope should the analysis cover?",
+    header: "Scope",
+    multiSelect: false,
+    options: [
+      {label: "Full Project", description: "Analyze entire codebase"},
+      {label: "Specific Module", description: "Focus on a specific module or directory"},
+      {label: "Custom Path", description: "Specify custom path pattern"}
+    ]
+  }]
+})
+```
+
+## Focus Areas Mapping
+
+| Report Type | Focus Areas |
+|-------------|-------------|
+| Architecture | Layer Structure, Module Dependencies, Entry Points, Data Flow |
+| Design | Design Patterns, Class Relationships, Interface Contracts, State Management |
+| Methods | Core Algorithms, Critical Paths, Public APIs, Complex Logic |
+| Comprehensive | All above combined |
+
+## Output
+
+Save configuration to `analysis-config.json`:
+
+```json
+{
+  "type": "architecture|design|methods|comprehensive",
+  "depth": "overview|detailed|deep-dive",
+  "scope": "**/*|src/**/*|custom",
+  "focus_areas": ["..."]
+}
+```
--- a/.claude/skills/project-analyze/phases/02-project-exploration.md
+++ b/.claude/skills/project-analyze/phases/02-project-exploration.md
@@ -0,0 +1,74 @@
+# Phase 2: Project Exploration
+
+Launch parallel exploration agents based on report type.
+
+## Execution
+
+### Step 1: Map Exploration Angles
+
+```javascript
+const angleMapping = {
+  architecture: ["Layer Structure", "Module Dependencies", "Entry Points", "Data Flow"],
+  design: ["Design Patterns", "Class Relationships", "Interface Contracts", "State Management"],
+  methods: ["Core Algorithms", "Critical Paths", "Public APIs", "Complex Logic"],
+  comprehensive: ["Layer Structure", "Design Patterns", "Core Algorithms", "Data Flow"]
+};
+
+const angles = angleMapping[config.type];
+```
+
+### Step 2: Launch Parallel Agents
+
+For each angle, launch an exploration agent:
+
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  description: `Explore: ${angle}`,
+  prompt: `
+## Exploration Objective
+Execute **${angle}** exploration for project analysis report.
+
+## Context
+- **Angle**: ${angle}
+- **Report Type**: ${config.type}
+- **Depth**: ${config.depth}
+- **Scope**: ${config.scope}
+
+## Exploration Protocol
+1. Structural Discovery (get_modules_by_depth, rg, glob)
+2. Pattern Recognition (conventions, naming, organization)
+3. Relationship Mapping (dependencies, integration points)
+
+## Output Format
+{
+  "angle": "${angle}",
+  "findings": {
+    "structure": [...],
+    "patterns": [...],
+    "relationships": [...],
+    "key_files": [{path, relevance, rationale}]
+  },
+  "insights": [...]
+}
+`
+})
+```
+
+### Step 3: Aggregate Results
+
+Merge all exploration results into unified findings:
+
+```javascript
+const aggregatedFindings = {
+  structure: [],      // from all angles
+  patterns: [],       // from all angles  
+  relationships: [],  // from all angles
+  key_files: [],      // deduplicated
+  insights: []        // prioritized
+};
+```
+
+## Output
+
+Save exploration results to `exploration-{angle}.json` files.
--- a/.claude/skills/project-analyze/phases/03-deep-analysis.md
+++ b/.claude/skills/project-analyze/phases/03-deep-analysis.md
@@ -0,0 +1,58 @@
+# Phase 3: Deep Analysis
+
+Execute deep analysis using Gemini CLI with exploration context.
+
+## Execution
+
+### Step 1: Prepare CLI Prompt
+
+```bash
+ccw cli -p "
+PURPOSE: Generate ${type} analysis report for project
+TASK: 
+  • Analyze project structure and patterns from ${type} perspective
+  • Focus on: ${focus_areas}
+  • Depth level: ${depth}
+  • Key files: ${key_files}
+MODE: analysis
+CONTEXT: @**/* | Exploration results
+EXPECTED: 
+  - Structured analysis
+  - Code references (file:line format)
+  - Mermaid diagram data
+  - Actionable insights
+RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md)
+" --tool gemini --mode analysis
+```
+
+### Step 2: Parse Analysis Results
+
+Extract structured data from CLI response:
+
+```javascript
+const deepAnalysis = {
+  findings: [],           // Analyzed findings with confidence scores
+  patterns: [],           // Identified patterns with consistency scores
+  dependencies: [],       // Dependency relationships
+  recommendations: [],    // Prioritized recommendations
+  sections: [],           // Report section data
+  diagram_data: {}        // Data for diagram generation
+};
+```
+
+### Step 3: Validate Analysis Quality
+
+Check analysis completeness:
+
+```javascript
+const qualityChecks = {
+  has_executive_summary: Boolean,
+  focus_areas_covered: config.focus_areas.every(area => analysis.covers(area)),
+  code_references_valid: analysis.references.every(ref => fileExists(ref)),
+  insights_actionable: analysis.insights.filter(i => i.actionable).length > 0
+};
+```
+
+## Output
+
+Save analysis results to `deep-analysis.json`.
--- a/.claude/skills/project-analyze/phases/03.5-diagram-generation.md
+++ b/.claude/skills/project-analyze/phases/03.5-diagram-generation.md
@@ -0,0 +1,86 @@
+# Phase 3.5: Diagram Generation
+
+Generate Mermaid diagrams based on report type and analysis data.
+
+> **Reference**: See [mermaid-utils.md](../../_shared/mermaid-utils.md) for utility functions.
+
+## Execution
+
+### Step 1: Determine Required Diagrams
+
+```javascript
+const diagramRequirements = {
+  architecture: [
+    {type: 'architecture', format: 'graph TD', file: 'architecture.mmd'},
+    {type: 'layers', format: 'graph TD', file: 'layers.mmd'},
+    {type: 'dependencies', format: 'graph LR', file: 'dependencies.mmd'},
+    {type: 'dataflow', format: 'flowchart LR', file: 'dataflow.mmd'}
+  ],
+  design: [
+    {type: 'class', format: 'classDiagram', file: 'class-diagram.mmd'},
+    {type: 'components', format: 'graph TD', file: 'components.mmd'},
+    {type: 'patterns', format: 'graph TD', file: 'patterns.mmd'},
+    {type: 'state', format: 'stateDiagram-v2', file: 'state.mmd'}
+  ],
+  methods: [
+    {type: 'algorithm', format: 'flowchart TD', file: 'algorithm-*.mmd'},
+    {type: 'sequence', format: 'sequenceDiagram', file: 'sequence-*.mmd'},
+    {type: 'critical_path', format: 'flowchart LR', file: 'critical-path.mmd'},
+    {type: 'api', format: 'graph LR', file: 'api.mmd'}
+  ],
+  comprehensive: [
+    {type: 'architecture', format: 'graph TD', file: 'architecture.mmd'},
+    {type: 'class', format: 'classDiagram', file: 'class-diagram.mmd'},
+    {type: 'sequence', format: 'sequenceDiagram', file: 'sequence-main.mmd'},
+    {type: 'dataflow', format: 'flowchart LR', file: 'dataflow.mmd'}
+  ]
+};
+
+const required = diagramRequirements[config.type];
+```
+
+### Step 2: Generate Each Diagram
+
+Use shared utilities from `../_shared/mermaid-utils.md`:
+
+```javascript
+// Import utilities
+const { sanitizeId, escapeLabel, generateClassDiagram, generateSequenceDiagram, validateMermaidSyntax } = require('../_shared/mermaid-utils.md');
+
+for (const diagram of required) {
+  const content = generateDiagram(diagram.type, diagram.format, analysisData);
+  Write(`${outputDir}/diagrams/${diagram.file}`, content);
+}
+```
+
+### Step 3: Validate All Diagrams
+
+```javascript
+const validationResults = validateDiagramDirectory(`${outputDir}/diagrams`);
+const failedDiagrams = validationResults.filter(r => !r.valid);
+
+if (failedDiagrams.length > 0) {
+  // Regenerate failed diagrams
+  for (const failed of failedDiagrams) {
+    regenerateDiagram(failed.file, failed.issues);
+  }
+}
+```
+
+### Step 4: Create Diagram Manifest
+
+```javascript
+Write(`${outputDir}/diagrams/manifest.json`, JSON.stringify({
+  generated_at: new Date().toISOString(),
+  diagrams: required.map(d => ({
+    type: d.type,
+    file: d.file,
+    format: d.format
+  })),
+  validation: validationResults
+}, null, 2));
+```
+
+## Output
+
+Save diagrams to `diagrams/` folder with `manifest.json`.
--- a/.claude/skills/project-analyze/phases/04-report-generation.md
+++ b/.claude/skills/project-analyze/phases/04-report-generation.md
@@ -0,0 +1,94 @@
+# Phase 4: Report Generation
+
+Assemble analysis and diagrams into structured Markdown report.
+
+## Execution
+
+### Step 1: Determine Report Sections
+
+```javascript
+const reportSections = {
+  architecture: [
+    "# Architecture Report",
+    "## Executive Summary",
+    "## System Overview",
+    "## Layer Analysis",
+    "## Module Dependencies",
+    "## Data Flow",
+    "## Entry Points & Critical Paths",
+    "## Dependency Graph",
+    "## Recommendations"
+  ],
+  design: [
+    "# Design Report",
+    "## Executive Summary",
+    "## Design Patterns Used",
+    "## Class Relationships",
+    "## Interface Contracts",
+    "## State Management",
+    "## Component Diagrams",
+    "## Design Recommendations"
+  ],
+  methods: [
+    "# Key Methods Report",
+    "## Executive Summary",
+    "## Core Algorithms",
+    "## Critical Code Paths",
+    "## Public API Reference",
+    "## Complex Logic Breakdown",
+    "## Sequence Diagrams",
+    "## Optimization Suggestions"
+  ],
+  comprehensive: [
+    "# Comprehensive Project Analysis",
+    "## Executive Summary",
+    "## Architecture Overview",
+    "## Design Patterns & Principles",
+    "## Key Methods & Algorithms",
+    "## System Diagrams",
+    "## Recommendations & Next Steps"
+  ]
+};
+
+const sections = reportSections[config.type];
+```
+
+### Step 2: Generate Report Content
+
+```javascript
+let report = '';
+
+for (const section of sections) {
+  report += section + '\n\n';
+  
+  // Add section content from analysis
+  const sectionContent = generateSectionContent(section, deepAnalysis);
+  report += sectionContent + '\n\n';
+  
+  // Embed relevant diagrams
+  const relatedDiagrams = findRelatedDiagrams(section, diagrams);
+  for (const diagram of relatedDiagrams) {
+    report += `\`\`\`mermaid\n${Read(diagram.path)}\n\`\`\`\n\n`;
+  }
+}
+```
+
+### Step 3: Add Code References
+
+Format all code references as `file:line`:
+
+```javascript
+// Example: src/auth/login.ts:42
+const codeRef = `${finding.file}:${finding.line}`;
+```
+
+### Step 4: Write Report
+
+```javascript
+const reportFileName = `${config.type.toUpperCase()}-REPORT.md`;
+Write(`${outputDir}/${reportFileName}`, report);
+```
+
+## Output
+
+Generate `{TYPE}-REPORT.md` in output directory.
--- a/.claude/skills/project-analyze/phases/05-iterative-refinement.md
+++ b/.claude/skills/project-analyze/phases/05-iterative-refinement.md
@@ -0,0 +1,124 @@
+# Phase 5: Iterative Refinement
+
+Discovery-driven refinement based on analysis findings.
+
+## Execution
+
+### Step 1: Extract Discoveries
+
+```javascript
+function extractDiscoveries(deepAnalysis) {
+  return {
+    ambiguities: deepAnalysis.findings.filter(f => f.confidence < 0.7),
+    complexityHotspots: deepAnalysis.findings.filter(f => f.complexity === 'high'),
+    patternDeviations: deepAnalysis.patterns.filter(p => p.consistency < 0.8),
+    unclearDependencies: deepAnalysis.dependencies.filter(d => d.type === 'implicit'),
+    potentialIssues: deepAnalysis.recommendations.filter(r => r.priority === 'investigate'),
+    depthOpportunities: deepAnalysis.sections.filter(s => s.has_more_detail)
+  };
+}
+
+const discoveries = extractDiscoveries(deepAnalysis);
+```
+
+### Step 2: Build Dynamic Questions
+
+Questions emerge from discoveries, NOT predetermined:
+
+```javascript
+function buildDynamicQuestions(discoveries, config) {
+  const questions = [];
+
+  if (discoveries.ambiguities.length > 0) {
+    questions.push({
+      question: `Analysis found ambiguity in "${discoveries.ambiguities[0].area}". Which interpretation is correct?`,
+      header: "Clarify",
+      options: discoveries.ambiguities[0].interpretations
+    });
+  }
+
+  if (discoveries.complexityHotspots.length > 0) {
+    questions.push({
+      question: `These areas have high complexity. Which would you like explained?`,
+      header: "Deep-Dive",
+      multiSelect: true,
+      options: discoveries.complexityHotspots.slice(0, 4).map(h => ({
+        label: h.name,
+        description: h.summary
+      }))
+    });
+  }
+
+  if (discoveries.patternDeviations.length > 0) {
+    questions.push({
+      question: `Found pattern deviations. Should these be highlighted in the report?`,
+      header: "Patterns",
+      options: [
+        {label: "Yes, include analysis", description: "Add section explaining deviations"},
+        {label: "No, skip", description: "Omit from report"}
+      ]
+    });
+  }
+
+  // Always include action question
+  questions.push({
+    question: "How would you like to proceed?",
+    header: "Action",
+    options: [
+      {label: "Continue refining", description: "Address more discoveries"},
+      {label: "Finalize report", description: "Generate final output"},
+      {label: "Change scope", description: "Modify analysis scope"}
+    ]
+  });
+
+  return questions.slice(0, 4); // Max 4 questions
+}
+```
+
+### Step 3: Apply Refinements
+
+```javascript
+if (userAction === "Continue refining") {
+  // Apply selected refinements
+  for (const selection of userSelections) {
+    applyRefinement(selection, deepAnalysis, report);
+  }
+  
+  // Save iteration
+  Write(`${outputDir}/iterations/iteration-${iterationCount}.json`, {
+    timestamp: new Date().toISOString(),
+    discoveries: discoveries,
+    selections: userSelections,
+    changes: appliedChanges
+  });
+  
+  // Loop back to Step 1
+  iterationCount++;
+  goto Step1;
+}
+
+if (userAction === "Finalize report") {
+  // Proceed to final output
+  goto FinalizeReport;
+}
+```
+
+### Step 4: Finalize Report
+
+```javascript
+// Add iteration history to report metadata
+const finalReport = {
+  ...report,
+  metadata: {
+    iterations: iterationCount,
+    refinements_applied: allRefinements,
+    final_discoveries: discoveries
+  }
+};
+
+Write(`${outputDir}/${config.type.toUpperCase()}-REPORT.md`, finalReport);
+```
+
+## Output
+
+Updated report with refinements, saved iterations to `iterations/` folder.
--- a/.claude/skills/project-analyze/specs/quality-standards.md
+++ b/.claude/skills/project-analyze/specs/quality-standards.md
@@ -0,0 +1,115 @@
+# Quality Standards
+
+Quality gates and requirements for project analysis reports.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 4 | Check report structure before assembly | Report Requirements |
+| Phase 5 | Validate before each iteration | Quality Gates |
+| Phase 5 | Handle failures during refinement | Error Handling |
+
+---
+
+## Report Requirements
+
+**Use in Phase 4**: Ensure report includes all required elements.
+
+| Requirement | Check | How to Fix |
+|-------------|-------|------------|
+| Executive Summary | 3-5 key takeaways | Extract from analysis findings |
+| Visual diagrams | Valid Mermaid syntax | Use `../_shared/mermaid-utils.md` |
+| Code references | `file:line` format | Link to actual source locations |
+| Recommendations | Actionable, specific | Derive from analysis insights |
+| Consistent depth | Match user's depth level | Adjust detail per config.depth |
+
+---
+
+## Quality Gates
+
+**Use in Phase 5**: Run these checks before asking user questions.
+
+```javascript
+function runQualityGates(report, config, diagrams) {
+  const gates = [
+    {
+      name: "focus_areas_covered",
+      check: () => config.focus_areas.every(area =>
+        report.toLowerCase().includes(area.toLowerCase())
+      ),
+      fix: "Re-analyze missing focus areas"
+    },
+    {
+      name: "diagrams_valid",
+      check: () => diagrams.every(d => d.valid),
+      fix: "Regenerate failed diagrams with mermaid-utils"
+    },
+    {
+      name: "code_refs_accurate",
+      check: () => extractCodeRefs(report).every(ref => fileExists(ref)),
+      fix: "Update invalid file references"
+    },
+    {
+      name: "no_placeholders",
+      check: () => !report.includes('[TODO]') && !report.includes('[PLACEHOLDER]'),
+      fix: "Fill in all placeholder content"
+    },
+    {
+      name: "recommendations_specific",
+      check: () => !report.includes('consider') || report.includes('specifically'),
+      fix: "Make recommendations project-specific"
+    }
+  ];
+
+  const results = gates.map(g => ({...g, passed: g.check()}));
+  const allPassed = results.every(r => r.passed);
+
+  return { allPassed, results };
+}
+```
+
+**Integration with Phase 5**:
+```javascript
+// In 05-iterative-refinement.md
+const { allPassed, results } = runQualityGates(report, config, diagrams);
+
+if (allPassed) {
+  // All gates passed → ask user to confirm or finalize
+} else {
+  // Gates failed → include failed gates in discovery questions
+  const failedGates = results.filter(r => !r.passed);
+  discoveries.qualityIssues = failedGates;
+}
+```
+
+---
+
+## Error Handling
+
+**Use when**: Encountering errors during any phase.
+
+| Error | Detection | Recovery |
+|-------|-----------|----------|
+| CLI timeout | Bash exits with timeout | Reduce scope via `config.scope`, retry |
+| Exploration failure | Agent returns error | Fall back to `Read` + `Grep` directly |
+| User abandons | User selects "cancel" | Save to `iterations/`, allow resume |
+| Invalid scope path | Path doesn't exist | `AskUserQuestion` to correct path |
+| Diagram validation fails | `validateMermaidSyntax` returns issues | Regenerate with stricter escaping |
+
+**Recovery Flow**:
+```javascript
+try {
+  await executePhase(phase);
+} catch (error) {
+  const recovery = ERROR_HANDLERS[error.type];
+  if (recovery) {
+    await recovery.action(error, config);
+    // Retry phase or continue
+  } else {
+    // Save progress and ask user
+    Write(`${outputDir}/error-state.json`, { phase, error, config });
+    AskUserQuestion({ question: "遇到错误，如何处理？", ... });
+  }
+}
+```