Claude-Code-Workflow/.claude/commands/analysis/run.md

name, description, usage, argument-hint, examples

name	description	usage	argument-hint	examples
run	Analyze context packages using intelligent tools and generate structured analysis reports	/analysis:run --session <session_id> --context <context_package_path>	--session WFS-session-id --context path/to/context-package.json	/analysis:run --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json /analysis:run --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json

Analysis Run Command (/analysis:run)

Overview

Intelligent analysis engine that processes standardized context packages, executes deep analysis using multiple AI tools, and generates structured analysis reports.

Core Philosophy

• Context-Driven: Precise analysis based on comprehensive context
• Intelligent Tool Selection: Choose optimal analysis tools based on task characteristics
• Structured Output: Generate standardized analysis reports
• Configurable Analysis: Support different depth and focus levels

Core Responsibilities

• Context Package Parsing: Read and validate context-package.json
• Multi-Tool Orchestration: Execute parallel analysis using Gemini/Codex
• Perspective Synthesis: Collect and organize different tool viewpoints
• Consensus Analysis: Identify agreements and conflicts between tools
• Analysis Report Generation: Output multi-perspective ANALYSIS_RESULTS.md (NOT implementation plan)

Analysis Strategy Selection

Tool Selection by Task Complexity

Simple Tasks (≤3 modules):

• Primary Tool: Gemini (rapid understanding and pattern recognition)
• Support Tool: Code-index (structural analysis)
• Execution Mode: Single-round analysis, focus on existing patterns

Medium Tasks (4-6 modules):

• Primary Tool: Gemini (comprehensive analysis and architecture design)
• Support Tools: Code-index + Exa (external best practices)
• Execution Mode: Two-round analysis, understanding + architecture design

Complex Tasks (>6 modules):

• Primary Tools: Multi-tool collaboration (Gemini+Codex)
• Analysis Strategy: Layered analysis with progressive refinement
• Execution Mode: Three-round analysis, understand + design + validate

Tool Preferences by Tech Stack

{
  "frontend": {
    "primary": "gemini",
    "secondary": "codex",
    "focus": ["component_design", "state_management", "ui_patterns"]
  },
  "backend": {
    "primary": "codex",
    "secondary": "gemini",
    "focus": ["api_design", "data_flow", "security", "performance"]
  },
  "fullstack": {
    "primary": "gemini",
    "secondary": "codex",
    "focus": ["system_architecture", "integration", "data_consistency"]
  }
}

Execution Process

Phase 1: Session & Context Package Analysis

1. Session Validation

   # Validate session exists
   if [ ! -d ".workflow/${session_id}" ]; then
     echo "❌ Session ${session_id} not found"
     exit 1
   fi
   
   # Load session metadata
   session_metadata=".workflow/${session_id}/workflow-session.json"
   

2. Package Validation

   # Validate context-package.json format
   jq empty {context_package_path} || error "Invalid JSON format"
   

3. Task Feature Extraction

   • Parse task description and keywords
   • Load session task summaries for context
   • Identify tech stack and complexity
   • Determine analysis focus and objectives

4. Resource Inventory

   • Count files by type
   • Assess context size
   • Define analysis scope

Phase 2: Analysis Tool Selection & Preparation

1. Intelligent Tool Selection

   # Select analysis tools based on complexity and tech stack
   if [ "$complexity" = "simple" ]; then
     analysis_tools=("gemini")
   elif [ "$complexity" = "medium" ]; then
     analysis_tools=("gemini")
   else
     analysis_tools=("gemini" "codex")
   fi
   

2. Prompt Template Selection

   • Choose analysis templates based on task type
   • Customize prompts with context information
   • Optimize token usage efficiency

Phase 3: Multi-Tool Analysis Execution

1. Gemini Analysis (Comprehensive Understanding & Architecture Design)

   cd "$project_root" && ~/.claude/scripts/gemini-wrapper -p "
   PURPOSE: Deep understanding of project architecture, existing patterns, and design implementation architecture
   TASK: Comprehensive analysis of ${task_description}
   CONTEXT: $(cat ${context_package_path} | jq -r '.assets[] | select(.priority=="high") | .path' | head -15)
   EXPECTED:
   - Existing architecture pattern analysis
   - Relevant code component identification
   - Technical risk assessment
   - Implementation complexity evaluation
   - Detailed technical implementation architecture
   - Code organization structure recommendations
   - Interface design and data flow
   - Specific implementation steps
   RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on existing patterns, integration points, and comprehensive design
   "
   

2. Codex Analysis (Implementation Feasibility & Technical Validation)

   # Only used for complex tasks
   if [ "$complexity" = "complex" ]; then
     codex -C "$project_root" --full-auto exec "
     PURPOSE: Validate technical implementation feasibility
     TASK: Assess implementation risks and technical challenges for ${task_description}
     CONTEXT: Project codebase + Gemini analysis results
     EXPECTED: Technical feasibility report and risk assessment
     RULES: Focus on technical risks, performance impact, and maintenance costs
     " -s danger-full-access
   fi
   

Phase 4: Multi-Perspective Analysis Integration

1. Tool-Specific Result Organization

   • Organize Gemini analysis (comprehensive understanding, patterns & architecture design)
   • Organize Codex analysis (feasibility & validation)

2. Perspective Synthesis

   • Identify consensus points across tools
   • Document conflicting viewpoints
   • Provide synthesis recommendations

3. Analysis Report Generation

   • Generate multi-tool perspective ANALYSIS_RESULTS.md
   • Preserve individual tool insights
   • Provide consolidated recommendations (NOT detailed implementation plan)

Analysis Results Format

Generated ANALYSIS_RESULTS.md format (Multi-Tool Perspective Analysis):

# Multi-Tool Analysis Results

## Task Overview
- **Description**: {task_description}
- **Context Package**: {context_package_path}
- **Analysis Tools**: {tools_used}
- **Analysis Timestamp**: {timestamp}

## Tool-Specific Analysis

### 🧠 Gemini Analysis (Comprehensive Understanding & Architecture Design)
**Focus**: Existing codebase understanding, pattern identification, and technical architecture design

#### Current Architecture Assessment
- **Existing Patterns**: {identified_patterns}
- **Code Structure**: {current_structure}
- **Integration Points**: {integration_analysis}
- **Technical Debt**: {debt_assessment}

#### Compatibility Analysis
- **Framework Compatibility**: {framework_analysis}
- **Dependency Impact**: {dependency_analysis}
- **Migration Considerations**: {migration_notes}

#### Proposed Architecture
- **System Design**: {architectural_design}
- **Component Structure**: {component_design}
- **Data Flow**: {data_flow_design}
- **Interface Design**: {api_interface_design}

#### Implementation Strategy
- **Code Organization**: {code_structure_plan}
- **Module Dependencies**: {module_dependencies}
- **Testing Strategy**: {testing_approach}

### 🔧 Codex Analysis (Implementation & Technical Validation)
**Focus**: Implementation feasibility and technical validation

#### Feasibility Assessment
- **Technical Risks**: {implementation_risks}
- **Performance Impact**: {performance_analysis}
- **Resource Requirements**: {resource_assessment}
- **Maintenance Complexity**: {maintenance_analysis}

#### Implementation Recommendations
- **Tool Selection**: {recommended_tools}
- **Development Approach**: {development_strategy}
- **Quality Assurance**: {qa_recommendations}

## Synthesis & Consensus

### Consolidated Recommendations
- **Architecture Approach**: {consensus_architecture}
- **Implementation Priority**: {priority_recommendations}
- **Risk Mitigation**: {risk_mitigation_strategy}

### Tool Agreement Analysis
- **Consensus Points**: {agreed_recommendations}
- **Conflicting Views**: {conflicting_opinions}
- **Resolution Strategy**: {conflict_resolution}

### Task Decomposition Suggestions
1. **Primary Tasks**: {major_task_suggestions}
2. **Task Dependencies**: {dependency_mapping}
3. **Complexity Assessment**: {complexity_evaluation}

## Analysis Quality Metrics
- **Context Coverage**: {coverage_percentage}
- **Tool Consensus**: {consensus_level}
- **Analysis Depth**: {depth_assessment}
- **Confidence Score**: {overall_confidence}

Error Handling & Fallbacks

Common Error Handling

1. Context Package Not Found

   if [ ! -f "$context_package_path" ]; then
     echo "❌ Context package not found: $context_package_path"
     echo "→ Run /context:gather first to generate context package"
     exit 1
   fi
   

2. Tool Unavailability Handling

   # Use Codex when Gemini is unavailable
   if ! command -v ~/.claude/scripts/gemini-wrapper; then
     echo "⚠️ Gemini not available, falling back to Codex"
     analysis_tools=("codex")
   fi
   

3. Large Context Handling

   # Batch processing for large contexts
   context_size=$(jq '.assets | length' "$context_package_path")
   if [ "$context_size" -gt 50 ]; then
     echo "⚠️ Large context detected, using batch analysis"
     # Batch analysis logic
   fi
   

Performance Optimization

Analysis Optimization Strategies

• Parallel Analysis: Execute multiple tools in parallel to reduce total time
• Context Sharding: Analyze large projects by module shards
• Caching Mechanism: Reuse analysis results for similar contexts
• Incremental Analysis: Perform incremental analysis based on changes

Resource Management

# Set analysis timeout
timeout 600s analysis_command || {
  echo "⚠️ Analysis timeout, generating partial results"
  # Generate partial results
}

# Memory usage monitoring
memory_usage=$(ps -o pid,vsz,rss,comm -p $$)
if [ "$memory_usage" -gt "$memory_limit" ]; then
  echo "⚠️ High memory usage detected, optimizing..."
fi

Integration Points

Input Interface

• Required: --session parameter specifying session ID (e.g., WFS-auth)
• Required: --context parameter specifying context package path
• Optional: --depth specify analysis depth (quick|full|deep)
• Optional: --focus specify analysis focus areas

Output Interface

• Primary: ANALYSIS_RESULTS.md file
• Location: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
• Secondary: analysis-summary.json (machine-readable format)

Quality Assurance

Analysis Quality Checks

• Completeness Check: Ensure all required analysis sections are completed
• Consistency Check: Verify consistency of multi-tool analysis results
• Feasibility Validation: Ensure recommended implementation plans are feasible

Success Criteria

• Generate complete ANALYSIS_RESULTS.md file
• Include specific feasible task decomposition recommendations
• Analysis results highly relevant to context
• Execution time within reasonable range (<10 minutes)

Related Commands

• /context:gather - Generate context packages required by this command
• /workflow:plan - Call this command for analysis
• /task:create - Create specific tasks based on analysis results