mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
89f6ac6804
- 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.
1468 lines
47 KiB
Markdown
1468 lines
47 KiB
Markdown
---
|
|
name: analyze
|
|
description: Multi-phase iterative project analysis with user-guided focus, produces architecture/design/method reports through incremental updates
|
|
argument-hint: "[scope|path] [--type=architecture|design|methods|comprehensive]"
|
|
allowed-tools: Task(*), AskUserQuestion(*), Read(*), Bash(*), Glob(*), Grep(*), TodoWrite(*), Write(*)
|
|
---
|
|
|
|
# Workflow Docs Analyze Command (/workflow:docs:analyze)
|
|
|
|
## Overview
|
|
|
|
**Iterative project analysis command** that guides users through multi-phase analysis to produce tailored project reports. Uses multi-agent collaboration with incremental report updates based on user feedback.
|
|
|
|
**Core Differentiator**: Unlike static analysis tools, this command engages in multi-round dialogue to understand user's specific focus areas and iteratively refines reports until user satisfaction.
|
|
|
|
## Report Types
|
|
|
|
| Type | Focus | Output |
|
|
|------|-------|--------|
|
|
| `architecture` | System structure, module relationships, dependencies | ARCHITECTURE-REPORT.md |
|
|
| `design` | Design patterns, class diagrams, component interactions | DESIGN-REPORT.md |
|
|
| `methods` | Key algorithms, critical paths, core functions explained | METHODS-REPORT.md |
|
|
| `comprehensive` | All above combined | COMPREHENSIVE-REPORT.md |
|
|
|
|
## Execution Philosophy
|
|
|
|
**User-Centric Iteration Model**:
|
|
1. **Discover** user's actual analysis needs (not assume)
|
|
2. **Explore** codebase from multiple angles
|
|
3. **Generate** initial report with clear structure
|
|
4. **Iterate** based on user feedback until satisfied
|
|
5. **Finalize** polished report
|
|
|
|
## Execution Process
|
|
|
|
```
|
|
Input Parsing:
|
|
├─ Parse: scope/path (optional, defaults to project root)
|
|
└─ Parse: --type flag (optional, determines initial focus)
|
|
|
|
Phase 1: Requirements Discovery (AskUserQuestion)
|
|
├─ Ask: Report type preference (if not specified)
|
|
├─ Ask: Focus areas within chosen type
|
|
├─ Ask: Depth level (overview/detailed/deep-dive)
|
|
└─ Output: analysis_config object
|
|
|
|
Phase 2: Project Exploration (cli-explore-agent)
|
|
├─ Execute: Parallel exploration by focus areas
|
|
├─ Generate: exploration-{angle}.json files
|
|
└─ Output: explorations-manifest.json
|
|
|
|
Phase 3: Deep Analysis (Gemini CLI)
|
|
├─ Execute: Multi-dimensional analysis
|
|
├─ Generate: analysis-{dimension}.json files
|
|
└─ Output: analysis-manifest.json
|
|
|
|
Phase 4: Initial Report Generation
|
|
├─ Synthesize: Merge all analysis results
|
|
├─ Generate: {TYPE}-REPORT.md (draft)
|
|
└─ Output: Present report to user
|
|
|
|
Phase 5: Iterative Refinement (Loop)
|
|
├─ Ask: User feedback on current report
|
|
├─ Decision:
|
|
│ ├─ "satisfied" → Finalize and exit
|
|
│ ├─ "expand section X" → Deep-dive specific area
|
|
│ ├─ "add details on Y" → Augment with new analysis
|
|
│ └─ "change focus" → Re-run Phase 3 with new config
|
|
└─ Update: Incremental report modification
|
|
|
|
Finalize:
|
|
└─ Output: Final {TYPE}-REPORT.md
|
|
```
|
|
|
|
## 5-Phase Execution
|
|
|
|
### Phase 1: Requirements Discovery
|
|
|
|
**Purpose**: Understand user's actual analysis needs through interactive questioning
|
|
|
|
**Step 1.1: Initialize TodoWrite**
|
|
|
|
```javascript
|
|
TodoWrite([
|
|
{content: "Phase 1: Requirements Discovery", status: "in_progress", activeForm: "Discovering analysis requirements"},
|
|
{content: "Phase 2: Project Exploration", status: "pending", activeForm: "Exploring project structure"},
|
|
{content: "Phase 3: Deep Analysis", status: "pending", activeForm: "Performing deep analysis"},
|
|
{content: "Phase 4: Initial Report Generation", status: "pending", activeForm: "Generating initial report"},
|
|
{content: "Phase 5: Iterative Refinement", status: "pending", activeForm: "Refining report based on feedback"}
|
|
])
|
|
```
|
|
|
|
**Step 1.2: Report Type Selection (if not specified)**
|
|
|
|
```javascript
|
|
if (!type_specified) {
|
|
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 1.3: Focus Area Discovery**
|
|
|
|
```javascript
|
|
// Based on report type, ask focused questions
|
|
const focusQuestions = {
|
|
architecture: {
|
|
question: "Which architectural aspects are you most interested in?",
|
|
header: "Focus Areas",
|
|
multiSelect: true,
|
|
options: [
|
|
{label: "Layer Structure", description: "How the system is divided into layers (presentation, business, data)"},
|
|
{label: "Module Dependencies", description: "How modules depend on and communicate with each other"},
|
|
{label: "Entry Points", description: "How requests flow through the system from entry to response"},
|
|
{label: "Data Flow", description: "How data moves and transforms across the system"}
|
|
]
|
|
},
|
|
design: {
|
|
question: "Which design aspects do you want to understand?",
|
|
header: "Design Focus",
|
|
multiSelect: true,
|
|
options: [
|
|
{label: "Design Patterns", description: "Identify and explain patterns used in the codebase"},
|
|
{label: "Class Relationships", description: "Inheritance, composition, and associations between classes"},
|
|
{label: "Interface Contracts", description: "How components communicate through interfaces/protocols"},
|
|
{label: "State Management", description: "How application state is managed and mutated"}
|
|
]
|
|
},
|
|
methods: {
|
|
question: "What kind of method analysis do you need?",
|
|
header: "Method Focus",
|
|
multiSelect: true,
|
|
options: [
|
|
{label: "Core Algorithms", description: "Key algorithms that define the system's behavior"},
|
|
{label: "Critical Paths", description: "Most important execution flows in the application"},
|
|
{label: "Public APIs", description: "External-facing methods and their contracts"},
|
|
{label: "Complex Logic", description: "Methods with high cyclomatic complexity explained"}
|
|
]
|
|
}
|
|
};
|
|
|
|
AskUserQuestion({questions: [focusQuestions[selected_type]]})
|
|
```
|
|
|
|
**Step 1.4: Depth Level Selection**
|
|
|
|
```javascript
|
|
AskUserQuestion({
|
|
questions: [{
|
|
question: "How detailed should the analysis be?",
|
|
header: "Depth",
|
|
multiSelect: false,
|
|
options: [
|
|
{label: "Overview (Recommended)", description: "High-level understanding, suitable for onboarding or quick review"},
|
|
{label: "Detailed", description: "In-depth analysis with code examples and explanations"},
|
|
{label: "Deep-Dive", description: "Exhaustive analysis with implementation details and edge cases"}
|
|
]
|
|
}]
|
|
})
|
|
```
|
|
|
|
**Step 1.5: Store Analysis Config**
|
|
|
|
```javascript
|
|
const analysis_config = {
|
|
type: selected_type,
|
|
focus_areas: selected_focus_areas,
|
|
depth: selected_depth,
|
|
scope: scope_path || ".",
|
|
timestamp: new Date().toISOString()
|
|
};
|
|
|
|
// Create output directory
|
|
const outputDir = `.workflow/.scratchpad/analyze-${Date.now()}`;
|
|
bash(`mkdir -p ${outputDir}`);
|
|
Write(`${outputDir}/analysis-config.json`, JSON.stringify(analysis_config, null, 2));
|
|
```
|
|
|
|
**TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
|
|
|
|
---
|
|
|
|
### Phase 2: Project Exploration
|
|
|
|
**Purpose**: Multi-angle exploration based on user's focus areas
|
|
|
|
**Step 2.1: Launch Parallel Explore Agents**
|
|
|
|
```javascript
|
|
const explorationAngles = mapFocusToAngles(analysis_config.focus_areas);
|
|
// Examples:
|
|
// - "Layer Structure" → ["architecture", "dependencies"]
|
|
// - "Design Patterns" → ["patterns", "abstractions"]
|
|
// - "Core Algorithms" → ["algorithms", "complexity"]
|
|
|
|
const explorationTasks = explorationAngles.map((angle, index) =>
|
|
Task({
|
|
subagent_type: "cli-explore-agent",
|
|
run_in_background: false,
|
|
description: `Explore: ${angle}`,
|
|
prompt: `
|
|
## Exploration Objective
|
|
Execute **${angle}** exploration for project analysis report.
|
|
|
|
## Context
|
|
- **Angle**: ${angle}
|
|
- **Report Type**: ${analysis_config.type}
|
|
- **Depth**: ${analysis_config.depth}
|
|
- **Scope**: ${analysis_config.scope}
|
|
- **Output**: ${outputDir}/exploration-${angle}.json
|
|
|
|
## Exploration Protocol
|
|
|
|
**Step 1: Structural Discovery**
|
|
- Execute: ccw tool exec get_modules_by_depth '{}'
|
|
- Find files relevant to ${angle} using rg/glob
|
|
- Map directory structure and module boundaries
|
|
|
|
**Step 2: Pattern Recognition**
|
|
- Identify ${angle}-related patterns and conventions
|
|
- Note file naming, organization patterns
|
|
- Extract key abstractions
|
|
|
|
**Step 3: Relationship Mapping**
|
|
- Map dependencies and relationships
|
|
- Identify integration points
|
|
- Note coupling and cohesion patterns
|
|
|
|
## Output Format
|
|
{
|
|
"angle": "${angle}",
|
|
"findings": {
|
|
"structure": [...],
|
|
"patterns": [...],
|
|
"relationships": [...],
|
|
"key_files": [{path, relevance, rationale}]
|
|
},
|
|
"insights": [...],
|
|
"depth_notes": "${analysis_config.depth}-specific observations"
|
|
}
|
|
|
|
Write output to: ${outputDir}/exploration-${angle}.json
|
|
`
|
|
})
|
|
);
|
|
```
|
|
|
|
**Step 2.2: Generate Exploration Manifest**
|
|
|
|
```javascript
|
|
const manifest = {
|
|
config: analysis_config,
|
|
explorations: explorationAngles.map(angle => ({
|
|
angle,
|
|
file: `exploration-${angle}.json`
|
|
})),
|
|
timestamp: new Date().toISOString()
|
|
};
|
|
Write(`${outputDir}/explorations-manifest.json`, JSON.stringify(manifest, null, 2));
|
|
```
|
|
|
|
**TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
|
|
|
|
---
|
|
|
|
### Phase 3: Deep Analysis
|
|
|
|
**Purpose**: Use Gemini CLI for in-depth analysis based on exploration results
|
|
|
|
**Step 3.1: Synthesize Exploration Results**
|
|
|
|
```javascript
|
|
// Read all exploration files
|
|
const explorations = explorationAngles.map(angle =>
|
|
JSON.parse(Read(`${outputDir}/exploration-${angle}.json`))
|
|
);
|
|
|
|
// Extract key files to analyze
|
|
const keyFiles = explorations.flatMap(e => e.findings.key_files)
|
|
.sort((a, b) => b.relevance - a.relevance)
|
|
.slice(0, 20); // Top 20 most relevant files
|
|
```
|
|
|
|
**Step 3.2: Execute Deep Analysis via Gemini CLI**
|
|
|
|
```javascript
|
|
const analysisPrompt = buildAnalysisPrompt(analysis_config, keyFiles);
|
|
|
|
Bash({
|
|
command: `ccw cli -p "
|
|
PURPOSE: Generate ${analysis_config.type} analysis report for project
|
|
TASK:
|
|
• Analyze project structure and patterns from ${analysis_config.type} perspective
|
|
• Focus on: ${analysis_config.focus_areas.join(', ')}
|
|
• Depth level: ${analysis_config.depth}
|
|
• Key files to analyze: ${keyFiles.map(f => f.path).join(', ')}
|
|
MODE: analysis
|
|
CONTEXT: @**/* | Exploration results from ${outputDir}/
|
|
EXPECTED:
|
|
- Structured ${analysis_config.type} analysis
|
|
- Clear explanations with code references
|
|
- Mermaid diagrams where applicable
|
|
- Actionable insights
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) |
|
|
Focus on ${analysis_config.focus_areas.join(', ')} |
|
|
Depth: ${analysis_config.depth}
|
|
" --tool gemini --mode analysis`,
|
|
run_in_background: true,
|
|
timeout: 600000
|
|
});
|
|
```
|
|
|
|
**Step 3.3: Store Analysis Results**
|
|
|
|
```javascript
|
|
// After CLI completes, store structured results
|
|
Write(`${outputDir}/deep-analysis.json`, JSON.stringify({
|
|
type: analysis_config.type,
|
|
focus_areas: analysis_config.focus_areas,
|
|
analysis_result: cli_output,
|
|
diagrams: extracted_diagrams,
|
|
code_references: extracted_references
|
|
}, null, 2));
|
|
```
|
|
|
|
**TodoWrite**: Mark Phase 3 completed, Phase 3.5 in_progress
|
|
|
|
---
|
|
|
|
### Phase 3.5: Diagram Generation
|
|
|
|
**Purpose**: Generate Mermaid diagrams based on analysis results, tailored to report type
|
|
|
|
**Step 3.5.1: Determine Required Diagrams**
|
|
|
|
```javascript
|
|
// Map report types to required diagram types
|
|
const diagramRequirements = {
|
|
architecture: [
|
|
{type: 'architecture', format: 'graph TD', name: 'System Architecture'},
|
|
{type: 'layers', format: 'graph TD', name: 'Layer Structure'},
|
|
{type: 'dependencies', format: 'graph LR', name: 'Module Dependencies'},
|
|
{type: 'dataflow', format: 'flowchart LR', name: 'Data Flow'}
|
|
],
|
|
design: [
|
|
{type: 'class', format: 'classDiagram', name: 'Class Diagram'},
|
|
{type: 'components', format: 'graph TD', name: 'Component Diagram'},
|
|
{type: 'patterns', format: 'graph TD', name: 'Design Patterns'},
|
|
{type: 'state', format: 'stateDiagram-v2', name: 'State Management'}
|
|
],
|
|
methods: [
|
|
{type: 'algorithm', format: 'flowchart TD', name: 'Algorithm Flowchart'},
|
|
{type: 'sequence', format: 'sequenceDiagram', name: 'Call Sequence'},
|
|
{type: 'critical_path', format: 'flowchart LR', name: 'Critical Path'},
|
|
{type: 'api', format: 'graph LR', name: 'API Structure'}
|
|
],
|
|
comprehensive: [
|
|
{type: 'architecture', format: 'graph TD', name: 'System Architecture'},
|
|
{type: 'class', format: 'classDiagram', name: 'Class Diagram'},
|
|
{type: 'sequence', format: 'sequenceDiagram', name: 'Key Sequences'},
|
|
{type: 'dataflow', format: 'flowchart LR', name: 'Data Flow'}
|
|
]
|
|
};
|
|
|
|
const requiredDiagrams = diagramRequirements[config.type];
|
|
bash(`mkdir -p ${outputDir}/diagrams`);
|
|
```
|
|
|
|
**Step 3.5.2: Generate Architecture Diagrams (graph TD)**
|
|
|
|
```javascript
|
|
function generateArchitectureDiagram(analysis) {
|
|
let mermaid = 'graph TD\n';
|
|
|
|
// Subgraphs for layers/modules
|
|
const layers = analysis.structure?.layers || extractLayers(analysis);
|
|
for (const layer of layers) {
|
|
mermaid += ` subgraph ${sanitizeId(layer.name)}["${escapeLabel(layer.name)}"]\n`;
|
|
for (const component of layer.components || []) {
|
|
mermaid += ` ${sanitizeId(component.id)}["${escapeLabel(component.name)}"]\n`;
|
|
}
|
|
mermaid += ' end\n';
|
|
}
|
|
|
|
// Connections
|
|
const connections = analysis.relationships || [];
|
|
for (const conn of connections) {
|
|
const label = conn.label ? `|"${escapeLabel(conn.label)}"|` : '';
|
|
mermaid += ` ${sanitizeId(conn.from)} -->${label} ${sanitizeId(conn.to)}\n`;
|
|
}
|
|
|
|
// Styling
|
|
mermaid += '\n %% Styling\n';
|
|
mermaid += ' classDef core fill:#e1f5fe,stroke:#01579b\n';
|
|
mermaid += ' classDef external fill:#fff3e0,stroke:#e65100\n';
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
if (requiredDiagrams.some(d => d.type === 'architecture')) {
|
|
const archDiagram = generateArchitectureDiagram(deepAnalysis);
|
|
Write(`${outputDir}/diagrams/architecture.mmd`, archDiagram);
|
|
}
|
|
```
|
|
|
|
**Step 3.5.3: Generate Layer/Dependency Diagrams**
|
|
|
|
```javascript
|
|
function generateLayerDiagram(analysis) {
|
|
let mermaid = 'graph TD\n';
|
|
|
|
const layers = ['Presentation', 'Application', 'Domain', 'Infrastructure'];
|
|
const detectedLayers = analysis.layers || inferLayers(analysis);
|
|
|
|
for (let i = 0; i < detectedLayers.length; i++) {
|
|
const layer = detectedLayers[i];
|
|
mermaid += ` subgraph L${i}["${escapeLabel(layer.name)}"]\n`;
|
|
mermaid += ` direction LR\n`;
|
|
for (const mod of layer.modules || []) {
|
|
mermaid += ` ${sanitizeId(mod)}["${escapeLabel(mod)}"]\n`;
|
|
}
|
|
mermaid += ' end\n';
|
|
|
|
if (i < detectedLayers.length - 1) {
|
|
mermaid += ` L${i} --> L${i + 1}\n`;
|
|
}
|
|
}
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
function generateDependencyDiagram(analysis) {
|
|
let mermaid = 'graph LR\n';
|
|
|
|
const modules = analysis.modules || [];
|
|
const deps = analysis.dependencies || [];
|
|
|
|
// Nodes
|
|
for (const mod of modules) {
|
|
const shape = mod.type === 'core' ? '([' : '[';
|
|
const shapeEnd = mod.type === 'core' ? '])' : ']';
|
|
mermaid += ` ${sanitizeId(mod.name)}${shape}"${escapeLabel(mod.name)}"${shapeEnd}\n`;
|
|
}
|
|
|
|
// Edges with labels
|
|
for (const dep of deps) {
|
|
const style = dep.type === 'weak' ? '-.->' : '-->';
|
|
const label = dep.count ? `|"${dep.count} refs"|` : '';
|
|
mermaid += ` ${sanitizeId(dep.from)} ${style}${label} ${sanitizeId(dep.to)}\n`;
|
|
}
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
if (requiredDiagrams.some(d => d.type === 'layers')) {
|
|
Write(`${outputDir}/diagrams/layers.mmd`, generateLayerDiagram(deepAnalysis));
|
|
}
|
|
if (requiredDiagrams.some(d => d.type === 'dependencies')) {
|
|
Write(`${outputDir}/diagrams/dependencies.mmd`, generateDependencyDiagram(deepAnalysis));
|
|
}
|
|
```
|
|
|
|
**Step 3.5.4: Generate Class Diagrams (classDiagram)**
|
|
|
|
```javascript
|
|
function generateClassDiagram(analysis) {
|
|
let mermaid = 'classDiagram\n';
|
|
|
|
const entities = analysis.entities || analysis.classes || [];
|
|
|
|
// Classes with properties and methods
|
|
for (const entity of entities.slice(0, 15)) { // Limit for readability
|
|
mermaid += ` class ${sanitizeId(entity.name)} {\n`;
|
|
|
|
// Properties
|
|
for (const prop of (entity.properties || []).slice(0, 8)) {
|
|
const vis = {public: '+', private: '-', protected: '#'}[prop.visibility] || '+';
|
|
mermaid += ` ${vis}${sanitizeType(prop.type)} ${prop.name}\n`;
|
|
}
|
|
|
|
// Methods
|
|
for (const method of (entity.methods || []).slice(0, 6)) {
|
|
const vis = {public: '+', private: '-', protected: '#'}[method.visibility] || '+';
|
|
const params = (method.params || []).map(p => `${p.name}`).join(', ');
|
|
mermaid += ` ${vis}${method.name}(${params}) ${sanitizeType(method.returnType || 'void')}\n`;
|
|
}
|
|
|
|
mermaid += ' }\n';
|
|
}
|
|
|
|
// Relationships
|
|
const relationships = analysis.relationships || [];
|
|
const arrows = {
|
|
inheritance: '--|>',
|
|
implementation: '..|>',
|
|
composition: '*--',
|
|
aggregation: 'o--',
|
|
association: '-->',
|
|
dependency: '..>'
|
|
};
|
|
|
|
for (const rel of relationships) {
|
|
const arrow = arrows[rel.type] || '-->';
|
|
const label = rel.label ? ` : ${escapeLabel(rel.label)}` : '';
|
|
mermaid += ` ${sanitizeId(rel.from)} ${arrow} ${sanitizeId(rel.to)}${label}\n`;
|
|
}
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
if (requiredDiagrams.some(d => d.type === 'class')) {
|
|
Write(`${outputDir}/diagrams/class-diagram.mmd`, generateClassDiagram(deepAnalysis));
|
|
}
|
|
```
|
|
|
|
**Step 3.5.5: Generate Flowcharts (flowchart TD)**
|
|
|
|
```javascript
|
|
function generateAlgorithmFlowchart(algorithm) {
|
|
let mermaid = 'flowchart TD\n';
|
|
|
|
// Start
|
|
mermaid += ` START(["Start: ${escapeLabel(algorithm.name)}"])\n`;
|
|
|
|
// Input processing
|
|
if (algorithm.inputs?.length > 0) {
|
|
mermaid += ` INPUT[/"Input: ${algorithm.inputs.map(i => i.name).join(', ')}"/]\n`;
|
|
mermaid += ' START --> INPUT\n';
|
|
}
|
|
|
|
// Process steps
|
|
let prevNode = algorithm.inputs?.length > 0 ? 'INPUT' : 'START';
|
|
for (let i = 0; i < (algorithm.steps || []).length; i++) {
|
|
const step = algorithm.steps[i];
|
|
const nodeId = `STEP${i}`;
|
|
|
|
if (step.type === 'decision') {
|
|
mermaid += ` ${nodeId}{"${escapeLabel(step.description)}"}\n`;
|
|
mermaid += ` ${prevNode} --> ${nodeId}\n`;
|
|
if (step.yes_branch) {
|
|
mermaid += ` ${nodeId} -->|"Yes"| ${sanitizeId(step.yes_branch)}\n`;
|
|
}
|
|
if (step.no_branch) {
|
|
mermaid += ` ${nodeId} -->|"No"| ${sanitizeId(step.no_branch)}\n`;
|
|
}
|
|
} else {
|
|
mermaid += ` ${nodeId}["${escapeLabel(step.description)}"]\n`;
|
|
mermaid += ` ${prevNode} --> ${nodeId}\n`;
|
|
}
|
|
prevNode = nodeId;
|
|
}
|
|
|
|
// Output and end
|
|
mermaid += ` OUTPUT[/"Output: ${escapeLabel(algorithm.output || 'Result')}"/]\n`;
|
|
mermaid += ` ${prevNode} --> OUTPUT\n`;
|
|
mermaid += ' END_([End])\n';
|
|
mermaid += ' OUTPUT --> END_\n';
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
function generateDataFlowDiagram(analysis) {
|
|
let mermaid = 'flowchart LR\n';
|
|
|
|
const flows = analysis.dataFlows || [];
|
|
|
|
// Data stores
|
|
mermaid += ' subgraph DataStores["Data Stores"]\n';
|
|
for (const store of analysis.dataStores || []) {
|
|
mermaid += ` ${sanitizeId(store.id)}[("${escapeLabel(store.name)}")]\n`;
|
|
}
|
|
mermaid += ' end\n';
|
|
|
|
// Processes
|
|
mermaid += ' subgraph Processes["Processes"]\n';
|
|
for (const proc of analysis.processes || []) {
|
|
mermaid += ` ${sanitizeId(proc.id)}["${escapeLabel(proc.name)}"]\n`;
|
|
}
|
|
mermaid += ' end\n';
|
|
|
|
// Flows
|
|
for (const flow of flows) {
|
|
mermaid += ` ${sanitizeId(flow.from)} -->|"${escapeLabel(flow.data)}"| ${sanitizeId(flow.to)}\n`;
|
|
}
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
// Generate algorithm flowcharts
|
|
const algorithms = deepAnalysis.algorithms || [];
|
|
for (const algo of algorithms.slice(0, 3)) { // Top 3 algorithms
|
|
const flowchart = generateAlgorithmFlowchart(algo);
|
|
Write(`${outputDir}/diagrams/algorithm-${sanitizeId(algo.name)}.mmd`, flowchart);
|
|
}
|
|
|
|
if (requiredDiagrams.some(d => d.type === 'dataflow')) {
|
|
Write(`${outputDir}/diagrams/dataflow.mmd`, generateDataFlowDiagram(deepAnalysis));
|
|
}
|
|
```
|
|
|
|
**Step 3.5.6: Generate Sequence Diagrams (sequenceDiagram)**
|
|
|
|
```javascript
|
|
function generateSequenceDiagram(scenario) {
|
|
let mermaid = 'sequenceDiagram\n';
|
|
|
|
// Title
|
|
mermaid += ` title ${escapeLabel(scenario.name)}\n`;
|
|
|
|
// Participants
|
|
for (const actor of scenario.actors || []) {
|
|
const type = actor.type === 'external' ? 'actor' : 'participant';
|
|
mermaid += ` ${type} ${sanitizeId(actor.id)} as ${escapeLabel(actor.name)}\n`;
|
|
}
|
|
|
|
mermaid += '\n';
|
|
|
|
// Messages
|
|
for (const msg of scenario.messages || []) {
|
|
let arrow;
|
|
switch (msg.type) {
|
|
case 'async': arrow = '->>'; break;
|
|
case 'response': arrow = '-->>'; break;
|
|
case 'create': arrow = '->>+'; break;
|
|
case 'destroy': arrow = '->>-'; break;
|
|
default: arrow = '->>';
|
|
}
|
|
|
|
mermaid += ` ${sanitizeId(msg.from)}${arrow}${sanitizeId(msg.to)}: ${escapeLabel(msg.description)}\n`;
|
|
|
|
// Activations
|
|
if (msg.activate) {
|
|
mermaid += ` activate ${sanitizeId(msg.to)}\n`;
|
|
}
|
|
if (msg.deactivate) {
|
|
mermaid += ` deactivate ${sanitizeId(msg.from)}\n`;
|
|
}
|
|
|
|
// Notes
|
|
if (msg.note) {
|
|
mermaid += ` Note over ${sanitizeId(msg.to)}: ${escapeLabel(msg.note)}\n`;
|
|
}
|
|
}
|
|
|
|
// Loops and conditions
|
|
for (const block of scenario.blocks || []) {
|
|
if (block.type === 'loop') {
|
|
mermaid += ` loop ${escapeLabel(block.condition)}\n`;
|
|
for (const m of block.messages) {
|
|
mermaid += ` ${sanitizeId(m.from)}->>${sanitizeId(m.to)}: ${escapeLabel(m.description)}\n`;
|
|
}
|
|
mermaid += ' end\n';
|
|
}
|
|
}
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
// Generate sequence diagrams for key scenarios
|
|
const scenarios = deepAnalysis.sequences || deepAnalysis.scenarios || [];
|
|
for (const scenario of scenarios.slice(0, 3)) {
|
|
const seqDiagram = generateSequenceDiagram(scenario);
|
|
Write(`${outputDir}/diagrams/sequence-${sanitizeId(scenario.name)}.mmd`, seqDiagram);
|
|
}
|
|
```
|
|
|
|
**Step 3.5.7: Generate State Diagrams (stateDiagram-v2)**
|
|
|
|
```javascript
|
|
function generateStateDiagram(stateAnalysis) {
|
|
let mermaid = 'stateDiagram-v2\n';
|
|
|
|
const states = stateAnalysis.states || [];
|
|
const transitions = stateAnalysis.transitions || [];
|
|
|
|
// States
|
|
for (const state of states) {
|
|
if (state.type === 'initial') {
|
|
mermaid += ` [*] --> ${sanitizeId(state.name)}\n`;
|
|
} else if (state.type === 'final') {
|
|
mermaid += ` ${sanitizeId(state.name)} --> [*]\n`;
|
|
} else if (state.substates) {
|
|
mermaid += ` state ${sanitizeId(state.name)} {\n`;
|
|
for (const sub of state.substates) {
|
|
mermaid += ` ${sanitizeId(sub.name)}\n`;
|
|
}
|
|
mermaid += ' }\n';
|
|
} else {
|
|
mermaid += ` ${sanitizeId(state.name)} : ${escapeLabel(state.description || state.name)}\n`;
|
|
}
|
|
}
|
|
|
|
// Transitions
|
|
for (const trans of transitions) {
|
|
const label = trans.event ? ` : ${escapeLabel(trans.event)}` : '';
|
|
mermaid += ` ${sanitizeId(trans.from)} --> ${sanitizeId(trans.to)}${label}\n`;
|
|
}
|
|
|
|
return mermaid;
|
|
}
|
|
|
|
if (requiredDiagrams.some(d => d.type === 'state')) {
|
|
const stateAnalysis = deepAnalysis.stateManagement || {};
|
|
if (stateAnalysis.states?.length > 0) {
|
|
Write(`${outputDir}/diagrams/state.mmd`, generateStateDiagram(stateAnalysis));
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 3.5.8: Helper Functions & Validation**
|
|
|
|
```javascript
|
|
// Sanitize ID for Mermaid (only alphanumeric and underscore)
|
|
function sanitizeId(text) {
|
|
return text.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[0-9]/, '_$&');
|
|
}
|
|
|
|
// Escape special characters in labels
|
|
function escapeLabel(text) {
|
|
if (!text) return '';
|
|
return text
|
|
.replace(/"/g, "'")
|
|
.replace(/[(){}[\]<>]/g, char => `#${char.charCodeAt(0)};`)
|
|
.substring(0, 50); // Limit length
|
|
}
|
|
|
|
// Sanitize type names
|
|
function sanitizeType(type) {
|
|
if (!type) return 'any';
|
|
return type.replace(/[<>]/g, '').replace(/\|/g, ' or ');
|
|
}
|
|
|
|
// Validate all generated diagrams
|
|
function validateMermaidDiagrams(diagramDir) {
|
|
const files = Glob(`${diagramDir}/*.mmd`);
|
|
const results = [];
|
|
|
|
for (const file of files) {
|
|
const content = Read(file);
|
|
const issues = [];
|
|
|
|
// Check for common syntax errors
|
|
if (content.includes('undefined')) issues.push('Contains undefined');
|
|
if (content.match(/-->.*-->/)) issues.push('Double arrow syntax');
|
|
if (!content.match(/^(graph|flowchart|classDiagram|sequenceDiagram|stateDiagram)/m)) {
|
|
issues.push('Missing diagram type declaration');
|
|
}
|
|
|
|
// Check for unescaped special chars in labels
|
|
const labelMatches = content.match(/\["[^"]*[(){}[\]<>][^"]*"\]/g);
|
|
if (labelMatches?.some(m => !m.includes('#'))) {
|
|
issues.push('Unescaped special characters in labels');
|
|
}
|
|
|
|
results.push({
|
|
file: file.split('/').pop(),
|
|
valid: issues.length === 0,
|
|
issues
|
|
});
|
|
}
|
|
|
|
return results;
|
|
}
|
|
|
|
const validationResults = validateMermaidDiagrams(`${outputDir}/diagrams`);
|
|
Write(`${outputDir}/diagrams/validation.json`, JSON.stringify(validationResults, null, 2));
|
|
|
|
// Log validation summary
|
|
const validCount = validationResults.filter(r => r.valid).length;
|
|
console.log(`Diagram Validation: ${validCount}/${validationResults.length} passed`);
|
|
```
|
|
|
|
**Step 3.5.9: Generate Diagram Manifest**
|
|
|
|
```javascript
|
|
const diagramManifest = {
|
|
report_type: config.type,
|
|
generated_at: new Date().toISOString(),
|
|
diagrams: requiredDiagrams.map(req => {
|
|
const filename = `${req.type}.mmd`;
|
|
const exists = file_exists(`${outputDir}/diagrams/${filename}`);
|
|
return {
|
|
type: req.type,
|
|
format: req.format,
|
|
name: req.name,
|
|
filename: exists ? filename : null,
|
|
status: exists ? 'generated' : 'skipped'
|
|
};
|
|
}),
|
|
validation: validationResults
|
|
};
|
|
|
|
Write(`${outputDir}/diagrams/manifest.json`, JSON.stringify(diagramManifest, null, 2));
|
|
```
|
|
|
|
**TodoWrite**: Mark Phase 3.5 completed, Phase 4 in_progress
|
|
|
|
---
|
|
|
|
### Phase 4: Initial Report Generation
|
|
|
|
**Purpose**: Synthesize all analysis into structured report
|
|
|
|
**Step 4.1: Load All Analysis Data and Diagrams**
|
|
|
|
```javascript
|
|
const config = JSON.parse(Read(`${outputDir}/analysis-config.json`));
|
|
const explorations = JSON.parse(Read(`${outputDir}/explorations-manifest.json`));
|
|
const deepAnalysis = JSON.parse(Read(`${outputDir}/deep-analysis.json`));
|
|
const diagramManifest = JSON.parse(Read(`${outputDir}/diagrams/manifest.json`));
|
|
|
|
// Load all generated diagrams
|
|
const diagrams = {};
|
|
for (const diag of diagramManifest.diagrams.filter(d => d.status === 'generated')) {
|
|
diagrams[diag.type] = Read(`${outputDir}/diagrams/${diag.filename}`);
|
|
}
|
|
```
|
|
|
|
**Step 4.2: Generate Report Structure**
|
|
|
|
```javascript
|
|
const reportTemplate = getReportTemplate(config.type);
|
|
// Templates define section structure for each report type
|
|
|
|
const reportSections = {
|
|
architecture: [
|
|
"# Architecture Report",
|
|
"## Executive Summary",
|
|
"## System Overview",
|
|
"## Layer Analysis",
|
|
"## Module Dependencies",
|
|
"## Data Flow",
|
|
"## Entry Points & Critical Paths",
|
|
"## Dependency Graph (Mermaid)",
|
|
"## Recommendations"
|
|
],
|
|
design: [
|
|
"# Design Report",
|
|
"## Executive Summary",
|
|
"## Design Patterns Used",
|
|
"## Class Relationships",
|
|
"## Interface Contracts",
|
|
"## State Management",
|
|
"## Component Diagrams (Mermaid)",
|
|
"## Design Recommendations"
|
|
],
|
|
methods: [
|
|
"# Key Methods Report",
|
|
"## Executive Summary",
|
|
"## Core Algorithms",
|
|
"## Critical Code Paths",
|
|
"## Public API Reference",
|
|
"## Complex Logic Breakdown",
|
|
"## Sequence Diagrams (Mermaid)",
|
|
"## Optimization Suggestions"
|
|
],
|
|
comprehensive: [
|
|
"# Comprehensive Project Analysis",
|
|
"## Executive Summary",
|
|
"## Architecture Overview",
|
|
"## Design Patterns & Principles",
|
|
"## Key Methods & Algorithms",
|
|
"## System Diagrams",
|
|
"## Recommendations & Next Steps"
|
|
]
|
|
};
|
|
```
|
|
|
|
**Step 4.3: Generate Initial Report**
|
|
|
|
```javascript
|
|
const reportPath = `${outputDir}/${config.type.toUpperCase()}-REPORT.md`;
|
|
const report = generateReport(reportSections[config.type], explorations, deepAnalysis);
|
|
Write(reportPath, report);
|
|
```
|
|
|
|
**Step 4.4: Present to User**
|
|
|
|
```markdown
|
|
## Initial Report Generated
|
|
|
|
**Report Type**: ${config.type}
|
|
**Focus Areas**: ${config.focus_areas.join(', ')}
|
|
**Depth**: ${config.depth}
|
|
|
|
**Output**: ${reportPath}
|
|
|
|
### Report Preview
|
|
[First 50 lines of report...]
|
|
|
|
---
|
|
**Ready for your feedback.** The report can be refined based on your input.
|
|
```
|
|
|
|
**TodoWrite**: Mark Phase 4 completed, Phase 5 in_progress
|
|
|
|
---
|
|
|
|
### Phase 5: Iterative Refinement (Discovery-Driven)
|
|
|
|
**Purpose**: Generate targeted questions based on agent analysis findings, then refine report based on user responses
|
|
|
|
**Core Philosophy**: Questions are NOT predetermined. They emerge from what the agent discovered during analysis.
|
|
|
|
**Step 5.1: Extract Discoveries from Analysis**
|
|
|
|
```javascript
|
|
// Parse deep analysis results for actionable discoveries
|
|
function extractDiscoveries(deepAnalysis) {
|
|
return {
|
|
// Ambiguities: Areas where analysis found multiple interpretations
|
|
ambiguities: deepAnalysis.findings.filter(f => f.confidence < 0.7),
|
|
|
|
// Complexity hotspots: Areas that may need deeper explanation
|
|
complexityHotspots: deepAnalysis.findings.filter(f => f.complexity === 'high'),
|
|
|
|
// Pattern variations: Where code deviates from expected patterns
|
|
patternDeviations: deepAnalysis.patterns.filter(p => p.consistency < 0.8),
|
|
|
|
// Unclear dependencies: Relationships that couldn't be fully traced
|
|
unclearDependencies: deepAnalysis.dependencies.filter(d => d.type === 'implicit'),
|
|
|
|
// Potential issues: Areas flagged for attention
|
|
potentialIssues: deepAnalysis.recommendations.filter(r => r.priority === 'investigate'),
|
|
|
|
// Depth opportunities: Sections that could benefit from expansion
|
|
depthOpportunities: deepAnalysis.sections.filter(s => s.has_more_detail)
|
|
};
|
|
}
|
|
|
|
const discoveries = extractDiscoveries(deepAnalysis);
|
|
```
|
|
|
|
**Step 5.2: Generate Dynamic Questions Based on Discoveries**
|
|
|
|
```javascript
|
|
function buildDynamicQuestions(discoveries, config) {
|
|
const questions = [];
|
|
|
|
// Question 1: Address ambiguities found
|
|
if (discoveries.ambiguities.length > 0) {
|
|
const topAmbiguity = discoveries.ambiguities[0];
|
|
questions.push({
|
|
question: `Analysis found ambiguity in "${topAmbiguity.area}": ${topAmbiguity.description}. Which interpretation is correct?`,
|
|
header: "Clarify",
|
|
multiSelect: false,
|
|
options: topAmbiguity.interpretations.map((interp, i) => ({
|
|
label: interp.summary,
|
|
description: interp.detail
|
|
}))
|
|
});
|
|
}
|
|
|
|
// Question 2: Complexity deep-dive selection
|
|
if (discoveries.complexityHotspots.length > 0) {
|
|
questions.push({
|
|
question: `These areas have high complexity. Which would you like explained in more detail?`,
|
|
header: "Deep-Dive",
|
|
multiSelect: true,
|
|
options: discoveries.complexityHotspots.slice(0, 4).map(h => ({
|
|
label: h.name,
|
|
description: `${h.file}:${h.line} - ${h.brief}`
|
|
}))
|
|
});
|
|
}
|
|
|
|
// Question 3: Pattern deviation confirmation
|
|
if (discoveries.patternDeviations.length > 0) {
|
|
const deviation = discoveries.patternDeviations[0];
|
|
questions.push({
|
|
question: `Found pattern inconsistency: "${deviation.pattern}" is used differently in ${deviation.locations.length} places. Should I analyze this deviation?`,
|
|
header: "Patterns",
|
|
multiSelect: false,
|
|
options: [
|
|
{label: "Yes, analyze differences", description: "Add detailed comparison to report"},
|
|
{label: "Skip, it's intentional", description: "Note as intentional variation"},
|
|
{label: "Flag as tech debt", description: "Add to recommendations section"}
|
|
]
|
|
});
|
|
}
|
|
|
|
// Question 4: Dependency clarification
|
|
if (discoveries.unclearDependencies.length > 0) {
|
|
questions.push({
|
|
question: `Found ${discoveries.unclearDependencies.length} implicit dependencies. Should I trace them fully?`,
|
|
header: "Dependencies",
|
|
multiSelect: false,
|
|
options: [
|
|
{label: "Yes, trace all (Recommended)", description: "Complete dependency graph, may take longer"},
|
|
{label: "Only critical paths", description: "Focus on main execution flows"},
|
|
{label: "Skip for now", description: "Keep current analysis level"}
|
|
]
|
|
});
|
|
}
|
|
|
|
// Always include satisfaction check as final question
|
|
questions.push({
|
|
question: "How would you like to proceed with the current report?",
|
|
header: "Action",
|
|
multiSelect: false,
|
|
options: [
|
|
{label: "Continue refining", description: "Apply above selections and show next discoveries"},
|
|
{label: "Finalize report", description: "Report meets my needs, generate final version"},
|
|
{label: "Change scope", description: "Adjust focus areas or analysis depth"}
|
|
]
|
|
});
|
|
|
|
return questions.slice(0, 4); // Max 4 questions per iteration
|
|
}
|
|
|
|
const dynamicQuestions = buildDynamicQuestions(discoveries, config);
|
|
AskUserQuestion({questions: dynamicQuestions});
|
|
```
|
|
|
|
**Step 5.3: Process User Responses and Update Analysis**
|
|
|
|
```javascript
|
|
function processResponses(responses, discoveries, deepAnalysis) {
|
|
const updates = [];
|
|
|
|
// Handle ambiguity resolution
|
|
if (responses.clarify) {
|
|
const resolution = {
|
|
area: discoveries.ambiguities[0].area,
|
|
resolved_to: responses.clarify,
|
|
confidence: 1.0 // User confirmed
|
|
};
|
|
updates.push({type: 'resolve_ambiguity', data: resolution});
|
|
}
|
|
|
|
// Handle deep-dive requests
|
|
if (responses.deepDive && responses.deepDive.length > 0) {
|
|
const deepDiveTargets = responses.deepDive;
|
|
updates.push({type: 'expand_sections', data: deepDiveTargets});
|
|
}
|
|
|
|
// Handle pattern deviation response
|
|
if (responses.patterns) {
|
|
updates.push({type: 'pattern_handling', data: responses.patterns});
|
|
}
|
|
|
|
// Handle dependency tracing
|
|
if (responses.dependencies) {
|
|
updates.push({type: 'dependency_depth', data: responses.dependencies});
|
|
}
|
|
|
|
return updates;
|
|
}
|
|
|
|
const updates = processResponses(user_responses, discoveries, deepAnalysis);
|
|
```
|
|
|
|
**Step 5.4: Incremental Analysis & Report Update**
|
|
|
|
```javascript
|
|
// Execute targeted re-analysis based on user responses
|
|
async function applyUpdates(updates, outputDir, config) {
|
|
for (const update of updates) {
|
|
switch (update.type) {
|
|
case 'expand_sections':
|
|
// Re-run Gemini CLI for specific sections only
|
|
for (const target of update.data) {
|
|
Bash({
|
|
command: `ccw cli -p "
|
|
PURPOSE: Deep-dive analysis of ${target.name}
|
|
TASK: Provide detailed explanation of ${target.file}:${target.line}
|
|
• Trace execution flow step by step
|
|
• Explain complex logic with examples
|
|
• Show relationships to other components
|
|
MODE: analysis
|
|
CONTEXT: @${target.file} | Previous analysis from ${outputDir}/
|
|
EXPECTED: Detailed section content for report insertion
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md)
|
|
" --tool gemini --mode analysis`,
|
|
run_in_background: true
|
|
});
|
|
}
|
|
break;
|
|
|
|
case 'resolve_ambiguity':
|
|
// Update analysis with confirmed interpretation
|
|
deepAnalysis.findings = deepAnalysis.findings.map(f =>
|
|
f.area === update.data.area
|
|
? {...f, interpretation: update.data.resolved_to, confidence: 1.0}
|
|
: f
|
|
);
|
|
break;
|
|
|
|
case 'dependency_depth':
|
|
if (update.data === 'Yes, trace all (Recommended)') {
|
|
// Launch dependency tracing agent
|
|
Task({
|
|
subagent_type: "cli-explore-agent",
|
|
description: "Trace full dependencies",
|
|
prompt: `Trace all implicit dependencies found in ${outputDir}/deep-analysis.json`
|
|
});
|
|
}
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
await applyUpdates(updates, outputDir, config);
|
|
|
|
// Regenerate report sections affected by updates
|
|
const currentReport = Read(reportPath);
|
|
const updatedSections = regenerateAffectedSections(currentReport, updates);
|
|
Write(reportPath, updatedSections);
|
|
Write(`${outputDir}/iterations/v${iteration_count}.md`, currentReport); // Archive previous version
|
|
```
|
|
|
|
**Step 5.5: Check Termination or Continue Loop**
|
|
|
|
```javascript
|
|
iteration_count++;
|
|
|
|
if (user_responses.action === 'Finalize report') {
|
|
// Exit refinement loop
|
|
finalized = true;
|
|
} else if (user_responses.action === 'Change scope') {
|
|
// Return to Phase 1 for scope adjustment
|
|
goto Phase1_Step1_3; // Focus area selection
|
|
} else {
|
|
// Extract new discoveries from updated analysis
|
|
const newDiscoveries = extractDiscoveries(deepAnalysis);
|
|
|
|
if (newDiscoveries.total_count === 0) {
|
|
// No more discoveries to clarify
|
|
console.log("All ambiguities resolved. Report is comprehensive.");
|
|
AskUserQuestion({
|
|
questions: [{
|
|
question: "No further clarifications needed. Finalize the report?",
|
|
header: "Complete",
|
|
multiSelect: false,
|
|
options: [
|
|
{label: "Yes, finalize", description: "Generate final polished report"},
|
|
{label: "Add custom section", description: "I want to add something specific"}
|
|
]
|
|
}]
|
|
});
|
|
} else {
|
|
// Continue with next round of discovery-driven questions
|
|
goto Step5.2;
|
|
}
|
|
}
|
|
|
|
// Safety limit
|
|
if (iteration_count > 7) {
|
|
console.log("Maximum refinement iterations reached. Finalizing report.");
|
|
finalized = true;
|
|
}
|
|
```
|
|
|
|
**Step 5.6: Discovery Summary Between Iterations**
|
|
|
|
```javascript
|
|
// Show user what was learned in this iteration
|
|
function summarizeIteration(iteration_count, updates, discoveries) {
|
|
return `
|
|
### Iteration ${iteration_count} Summary
|
|
|
|
**Clarifications Applied**: ${updates.filter(u => u.type === 'resolve_ambiguity').length}
|
|
**Sections Expanded**: ${updates.filter(u => u.type === 'expand_sections').length}
|
|
**Patterns Addressed**: ${updates.filter(u => u.type === 'pattern_handling').length}
|
|
|
|
**Remaining Discoveries**:
|
|
- Ambiguities: ${discoveries.ambiguities.length}
|
|
- Complexity hotspots: ${discoveries.complexityHotspots.length}
|
|
- Pattern deviations: ${discoveries.patternDeviations.length}
|
|
|
|
**Report Sections Updated**: [list affected sections]
|
|
`;
|
|
}
|
|
|
|
console.log(summarizeIteration(iteration_count, updates, discoveries));
|
|
```
|
|
|
|
---
|
|
|
|
### Finalization
|
|
|
|
**Step 6.1: Polish Final Report**
|
|
|
|
```javascript
|
|
// Add metadata and finalize formatting
|
|
const finalReport = `
|
|
<!-- Generated by /workflow:docs:analyze -->
|
|
<!-- Type: ${config.type} | Focus: ${config.focus_areas.join(', ')} | Depth: ${config.depth} -->
|
|
<!-- Generated: ${new Date().toISOString()} | Iterations: ${iteration_count} -->
|
|
|
|
${report_content}
|
|
|
|
---
|
|
*Report generated through ${iteration_count} refinement iterations.*
|
|
`;
|
|
|
|
Write(reportPath, finalReport);
|
|
```
|
|
|
|
**Step 6.2: Summary Output**
|
|
|
|
```markdown
|
|
## Analysis Complete
|
|
|
|
**Final Report**: ${reportPath}
|
|
**Report Type**: ${config.type}
|
|
**Focus Areas**: ${config.focus_areas.join(', ')}
|
|
**Refinement Iterations**: ${iteration_count}
|
|
|
|
### Report Contents
|
|
- ${section_count} sections
|
|
- ${diagram_count} Mermaid diagrams
|
|
- ${code_reference_count} code references
|
|
|
|
### Recommended Next Steps
|
|
1. Share report with team members
|
|
2. Use findings to guide development decisions
|
|
3. Run `/workflow:plan` to create implementation tasks based on recommendations
|
|
```
|
|
|
|
**TodoWrite**: Mark Phase 5 completed
|
|
|
|
---
|
|
|
|
## TodoWrite Pattern
|
|
|
|
**Dynamic Task Tracking** with phase-level visibility:
|
|
|
|
```javascript
|
|
// Initial state
|
|
[
|
|
{content: "Phase 1: Requirements Discovery", status: "pending", activeForm: "Discovering analysis requirements"},
|
|
{content: "Phase 2: Project Exploration", status: "pending", activeForm: "Exploring project structure"},
|
|
{content: "Phase 3: Deep Analysis", status: "pending", activeForm: "Performing deep analysis"},
|
|
{content: "Phase 3.5: Diagram Generation", status: "pending", activeForm: "Generating Mermaid diagrams"},
|
|
{content: "Phase 4: Initial Report Generation", status: "pending", activeForm: "Generating initial report"},
|
|
{content: "Phase 5: Iterative Refinement", status: "pending", activeForm: "Refining report based on feedback"}
|
|
]
|
|
|
|
// During Phase 3.5, show diagram generation progress
|
|
[
|
|
{content: "Phase 1: Requirements Discovery", status: "completed", activeForm: "Discovering analysis requirements"},
|
|
{content: "Phase 2: Project Exploration", status: "completed", activeForm: "Exploring project structure"},
|
|
{content: "Phase 3: Deep Analysis", status: "completed", activeForm: "Performing deep analysis"},
|
|
{content: "Phase 3.5: Diagram Generation", status: "in_progress", activeForm: "Generating Mermaid diagrams"},
|
|
{content: " → Architecture diagram", status: "completed", activeForm: "Generating architecture diagram"},
|
|
{content: " → Class diagram", status: "in_progress", activeForm: "Generating class diagram"},
|
|
{content: " → Sequence diagrams", status: "pending", activeForm: "Generating sequence diagrams"},
|
|
{content: "Phase 4: Initial Report Generation", status: "pending", activeForm: "Generating initial report"},
|
|
{content: "Phase 5: Iterative Refinement", status: "pending", activeForm: "Refining report based on feedback"}
|
|
]
|
|
|
|
// During Phase 5 iterations, expand to show current refinement
|
|
[
|
|
{content: "Phase 1: Requirements Discovery", status: "completed", activeForm: "Discovering analysis requirements"},
|
|
{content: "Phase 2: Project Exploration", status: "completed", activeForm: "Exploring project structure"},
|
|
{content: "Phase 3: Deep Analysis", status: "completed", activeForm: "Performing deep analysis"},
|
|
{content: "Phase 3.5: Diagram Generation", status: "completed", activeForm: "Generating Mermaid diagrams"},
|
|
{content: "Phase 4: Initial Report Generation", status: "completed", activeForm: "Generating initial report"},
|
|
{content: "Phase 5: Iterative Refinement", status: "in_progress", activeForm: "Refining report based on feedback"},
|
|
{content: " → Iteration 2: Expanding Architecture section", status: "in_progress", activeForm: "Expanding section"}
|
|
]
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
```bash
|
|
# Interactive analysis (prompts for all preferences)
|
|
/workflow:docs:analyze
|
|
|
|
# Architecture report for specific directory
|
|
/workflow:docs:analyze src/core --type=architecture
|
|
|
|
# Design patterns analysis
|
|
/workflow:docs:analyze --type=design
|
|
|
|
# Comprehensive analysis of entire project
|
|
/workflow:docs:analyze --type=comprehensive
|
|
|
|
# Key methods analysis for API module
|
|
/workflow:docs:analyze src/api --type=methods
|
|
```
|
|
|
|
## Output Structure
|
|
|
|
```
|
|
.workflow/.scratchpad/analyze-{timestamp}/
|
|
├── analysis-config.json # User's analysis preferences
|
|
├── exploration-{angle}.json # Per-angle exploration results
|
|
├── explorations-manifest.json # Exploration summary
|
|
├── deep-analysis.json # Gemini CLI analysis output
|
|
├── diagrams/ # Generated Mermaid diagrams
|
|
│ ├── manifest.json # Diagram generation manifest
|
|
│ ├── validation.json # Syntax validation results
|
|
│ ├── architecture.mmd # System architecture (graph TD)
|
|
│ ├── layers.mmd # Layer structure (graph TD)
|
|
│ ├── dependencies.mmd # Module dependencies (graph LR)
|
|
│ ├── class-diagram.mmd # Class relationships (classDiagram)
|
|
│ ├── dataflow.mmd # Data flow (flowchart LR)
|
|
│ ├── algorithm-*.mmd # Algorithm flowcharts (flowchart TD)
|
|
│ ├── sequence-*.mmd # Call sequences (sequenceDiagram)
|
|
│ └── state.mmd # State transitions (stateDiagram-v2)
|
|
├── {TYPE}-REPORT.md # Final report (main output)
|
|
└── iterations/ # Refinement history
|
|
├── v1-initial.md
|
|
├── v2-expanded.md
|
|
└── ...
|
|
```
|
|
|
|
## Report Quality Standards
|
|
|
|
**All reports must include**:
|
|
1. **Executive Summary**: 3-5 key takeaways
|
|
2. **Visual Diagrams**: Mermaid syntax for architecture/flow visualization
|
|
3. **Code References**: `file:line` format for easy navigation
|
|
4. **Actionable Insights**: Specific recommendations, not generic advice
|
|
5. **Consistent Depth**: Match user's selected depth level throughout
|
|
|
|
**Quality Gates**:
|
|
- [ ] All focus areas addressed
|
|
- [ ] Diagrams render correctly (Mermaid syntax valid)
|
|
- [ ] Code references are accurate (files exist)
|
|
- [ ] No placeholder content
|
|
- [ ] Recommendations are project-specific
|
|
|
|
## Error Handling
|
|
|
|
| Error | Recovery |
|
|
|-------|----------|
|
|
| CLI timeout | Reduce scope, retry with fewer files |
|
|
| Exploration failure | Fall back to direct file reading |
|
|
| User abandons iteration | Save current progress, allow resume |
|
|
| Invalid scope path | Prompt user to correct path |
|
|
|
|
## Related Commands
|
|
|
|
**Prerequisite Commands**:
|
|
- None required (can be run independently)
|
|
|
|
**Follow-up Commands**:
|
|
- `/workflow:plan` - Create implementation tasks from recommendations
|
|
- `/memory:docs` - Generate project documentation
|
|
- `/workflow:review` - Review specific areas identified in analysis
|
|
|
|
**Alternative Commands**:
|
|
- `/memory:code-map-memory` - For feature-specific code mapping
|
|
- `/memory:load` - For quick context loading without reports
|
|
|
|
---
|
|
|
|
## Mermaid Diagram Specifications
|
|
|
|
### Diagram Types by Report
|
|
|
|
| Report Type | Diagrams Generated |
|
|
|-------------|-------------------|
|
|
| `architecture` | architecture.mmd, layers.mmd, dependencies.mmd, dataflow.mmd |
|
|
| `design` | class-diagram.mmd, components.mmd, patterns.mmd, state.mmd |
|
|
| `methods` | algorithm-*.mmd, sequence-*.mmd, critical-path.mmd, api.mmd |
|
|
| `comprehensive` | architecture.mmd, class-diagram.mmd, sequence-*.mmd, dataflow.mmd |
|
|
|
|
### Syntax Rules (Ensuring Valid Diagrams)
|
|
|
|
```javascript
|
|
// 1. Node IDs: Only alphanumeric and underscore
|
|
sanitizeId("User-Service") → "User_Service"
|
|
sanitizeId("3rdParty") → "_3rdParty"
|
|
|
|
// 2. Labels: Escape special characters with HTML entities
|
|
escapeLabel("Process(data)") → "Process#40;data#41;"
|
|
escapeLabel("Check {valid?}") → "Check #123;valid?#125;"
|
|
|
|
// 3. Edge labels: Always use double quotes
|
|
// ✓ Correct
|
|
A -->|"calls(param)"| B
|
|
|
|
// ✗ Wrong
|
|
A -->|calls(param)| B
|
|
|
|
// 4. Subgraph titles: Use quoted labels
|
|
// ✓ Correct
|
|
subgraph ServiceLayer["Service Layer (Core)"]
|
|
|
|
// ✗ Wrong
|
|
subgraph ServiceLayer[Service Layer (Core)]
|
|
```
|
|
|
|
### Diagram Format Examples
|
|
|
|
**Architecture (graph TD)**:
|
|
```mermaid
|
|
graph TD
|
|
subgraph Presentation["Presentation Layer"]
|
|
API["API Gateway"]
|
|
CLI["CLI Interface"]
|
|
end
|
|
subgraph Business["Business Layer"]
|
|
SVC["Core Services"]
|
|
end
|
|
API --> SVC
|
|
CLI --> SVC
|
|
```
|
|
|
|
**Class Diagram (classDiagram)**:
|
|
```mermaid
|
|
classDiagram
|
|
class UserService {
|
|
+string name
|
|
+getUser(id) User
|
|
-validate() boolean
|
|
}
|
|
class Repository {
|
|
<<interface>>
|
|
+find(id) Entity
|
|
}
|
|
UserService --> Repository : uses
|
|
```
|
|
|
|
**Sequence Diagram (sequenceDiagram)**:
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant C as Client
|
|
participant S as Server
|
|
participant D as Database
|
|
C->>S: request(data)
|
|
activate S
|
|
S->>D: query
|
|
D-->>S: result
|
|
S-->>C: response
|
|
deactivate S
|
|
```
|
|
|
|
**Flowchart (flowchart TD)**:
|
|
```mermaid
|
|
flowchart TD
|
|
START(["Start"])
|
|
INPUT[/"Read input"/]
|
|
CHECK{"Valid?"}
|
|
PROCESS["Process data"]
|
|
OUTPUT[/"Write output"/]
|
|
END_(["End"])
|
|
|
|
START --> INPUT --> CHECK
|
|
CHECK -->|"Yes"| PROCESS --> OUTPUT --> END_
|
|
CHECK -->|"No"| END_
|
|
```
|
|
|
|
### Validation Checks
|
|
|
|
The diagram generator validates:
|
|
- [ ] Diagram type declaration present
|
|
- [ ] No `undefined` values in output
|
|
- [ ] Special characters properly escaped
|
|
- [ ] No double arrow syntax errors
|
|
- [ ] Subgraph brackets balanced
|
|
- [ ] Node IDs are valid identifiers
|