mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: add comprehensive review-session-cycle command for multi-dimensional code analysis
- Introduced a new command `/workflow:review-session-cycle` for session-based code reviews across 7 dimensions. - Implemented hybrid parallel-iterative execution to enhance review efficiency and coverage. - Added detailed documentation outlining command usage, execution flow, and agent roles. - Configured specialized dimensions with priority-based allocation and defined severity assessment criteria. - Established a robust aggregation logic for identifying cross-cutting concerns and critical findings. - Enabled real-time progress tracking through an interactive HTML dashboard. - Included mechanisms for deep-dive analysis and remediation planning for critical issues.
This commit is contained in:
catlog22
799
.claude/commands/workflow/review-module-cycle.md
Normal file
799
.claude/commands/workflow/review-module-cycle.md
Normal file
@@ -0,0 +1,799 @@
|
||||
---
|
||||
name: review-module-cycle
|
||||
description: Independent multi-dimensional code review for specified modules/files. Analyzes specific code paths across 7 dimensions with hybrid parallel-iterative execution, independent of workflow sessions.
|
||||
argument-hint: "<path-pattern> [--dimensions=security,architecture,...] [--max-iterations=N] [--output-dir=path] [--resume]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
|
||||
---
|
||||
|
||||
# Workflow Review-Module-Cycle Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Review specific module (all 7 dimensions)
|
||||
/workflow:review-module-cycle src/auth/**
|
||||
|
||||
# Review multiple modules
|
||||
/workflow:review-module-cycle src/auth/**,src/payment/**
|
||||
|
||||
# Review with custom dimensions
|
||||
/workflow:review-module-cycle src/payment/** --dimensions=security,architecture,quality
|
||||
|
||||
# Review specific files
|
||||
/workflow:review-module-cycle src/payment/processor.ts,src/payment/validator.ts
|
||||
|
||||
# Custom output directory
|
||||
/workflow:review-module-cycle src/auth/** --output-dir=.workflow/.scratchpad/reviews/auth-review
|
||||
|
||||
# Resume interrupted review
|
||||
/workflow:review-module-cycle --resume
|
||||
```
|
||||
|
||||
**Review Scope**: Specified modules/files only (independent of git history or sessions)
|
||||
**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
|
||||
**Max Iterations**: 3 (default, adjustable)
|
||||
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
Independent multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **specific modules or files**.
|
||||
|
||||
**Review Scope**:
|
||||
- **Module-based**: Reviews specified file patterns (e.g., `src/auth/**`, `*.ts`)
|
||||
- **No session dependency**: Works independently of workflow sessions
|
||||
- **For session-based review**: Use `/workflow:review-session-cycle` command instead
|
||||
|
||||
**vs Session Review**:
|
||||
- **Session Review** (`review-session-cycle`): Reviews git changes within a workflow session
|
||||
- **Module Review** (`review-module-cycle`): Reviews any specified code paths, regardless of git history
|
||||
|
||||
### Value Proposition
|
||||
1. **Ad-hoc Review**: Review any code without requiring a workflow session
|
||||
2. **Module-focused**: Target specific areas of codebase for deep analysis
|
||||
3. **Comprehensive Coverage**: Same 7 specialized dimensions as session review
|
||||
4. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns
|
||||
5. **Real-time Visibility**: JSON-based progress tracking with interactive HTML dashboard
|
||||
|
||||
### Orchestrator Boundary (CRITICAL)
|
||||
- **ONLY command** for independent multi-dimensional module review
|
||||
- Manages: dimension coordination, aggregation, iteration control, progress tracking
|
||||
- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode
|
||||
|
||||
## How It Works
|
||||
|
||||
### Execution Flow (Simplified)
|
||||
|
||||
```
|
||||
1. Discovery & Initialization
|
||||
└─ Resolve file patterns, validate paths, initialize state, create output structure → Generate dashboard.html
|
||||
|
||||
2. Phase 2: Parallel Reviews (for each dimension):
|
||||
├─ Launch 7 review agents simultaneously
|
||||
├─ Each executes CLI analysis via Gemini/Qwen on specified files
|
||||
├─ Generate dimension JSON + markdown reports
|
||||
└─ Update review-progress.json
|
||||
|
||||
3. Phase 3: Aggregation:
|
||||
├─ Load all dimension JSON files
|
||||
├─ Calculate severity distribution (critical/high/medium/low)
|
||||
├─ Identify cross-cutting concerns (files in 3+ dimensions)
|
||||
└─ Decision:
|
||||
├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate)
|
||||
└─ Else → Phase 5 (Complete)
|
||||
|
||||
4. Phase 4: Iterative Deep-Dive (optional):
|
||||
├─ Select critical findings (max 5 per iteration)
|
||||
├─ Launch deep-dive agents for root cause analysis
|
||||
├─ Generate remediation plans with impact assessment
|
||||
├─ Re-assess severity based on analysis
|
||||
└─ Loop until no critical findings OR max iterations
|
||||
|
||||
5. Phase 5: Completion
|
||||
└─ Generate REVIEW-SUMMARY.md → Output path
|
||||
```
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Orchestrator** | Phase control, path resolution, state management, aggregation logic, iteration control |
|
||||
| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports |
|
||||
| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment |
|
||||
|
||||
## Enhanced Features
|
||||
|
||||
### 1. Review Dimensions Configuration
|
||||
|
||||
**7 Specialized Dimensions** with priority-based allocation:
|
||||
|
||||
| Dimension | Template | Priority | Timeout |
|
||||
|-----------|----------|----------|---------|
|
||||
| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min |
|
||||
| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min |
|
||||
| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min |
|
||||
| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min |
|
||||
| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min |
|
||||
| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min |
|
||||
| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min |
|
||||
|
||||
*Custom focus: "Assess technical debt and maintainability"
|
||||
|
||||
**Category Definitions by Dimension**:
|
||||
|
||||
```javascript
|
||||
const CATEGORIES = {
|
||||
security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'],
|
||||
architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'],
|
||||
quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'],
|
||||
'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'],
|
||||
performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'],
|
||||
maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'],
|
||||
'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style']
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Path Pattern Resolution
|
||||
|
||||
**Supported Patterns**:
|
||||
- **Glob patterns**: `src/auth/**`, `src/payment/**/*.ts`
|
||||
- **Specific files**: `src/payment/processor.ts`
|
||||
- **Multiple patterns**: `src/auth/**,src/payment/**` (comma-separated)
|
||||
- **Extension filters**: `*.ts`, `**/*.test.ts`
|
||||
|
||||
**Resolution Process**:
|
||||
1. Parse input pattern (comma-separated if multiple)
|
||||
2. Expand glob patterns to file list
|
||||
3. Validate all files exist
|
||||
4. Store resolved file list in review-state.json
|
||||
|
||||
### 3. Aggregation Logic
|
||||
|
||||
**Cross-Cutting Concern Detection**:
|
||||
1. Files appearing in 3+ dimensions = **Critical Files**
|
||||
2. Same issue pattern across dimensions = **Systemic Issue**
|
||||
3. Severity clustering in specific files = **Hotspots**
|
||||
|
||||
**Deep-Dive Selection Criteria**:
|
||||
- All critical severity findings (priority 1)
|
||||
- Top 3 high-severity findings in critical files (priority 2)
|
||||
- Max 5 findings per iteration (prevent overwhelm)
|
||||
|
||||
### 4. Severity Assessment
|
||||
|
||||
**Severity Levels**:
|
||||
- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass
|
||||
- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt
|
||||
- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns
|
||||
- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues
|
||||
|
||||
**Iteration Trigger**:
|
||||
- Critical findings > 0 OR
|
||||
- High findings > 5 OR
|
||||
- Critical files count > 0
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Orchestrator
|
||||
|
||||
**Phase 1: Discovery & Initialization**
|
||||
- Path resolution: Parse and expand file patterns (glob support)
|
||||
- Validation: Ensure all specified files exist and are readable
|
||||
- State initialization: Create review-state.json with dimensions, max_iterations, resolved_files
|
||||
- Directory structure: Create output-dir/{dimensions,iterations,reports}/
|
||||
- Dashboard generation: Generate dashboard.html from template (see Dashboard Generation below)
|
||||
- TodoWrite initialization: Set up progress tracking
|
||||
|
||||
**Phase 2: Parallel Review Coordination**
|
||||
- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
|
||||
- Pass dimension-specific context (template, timeout, custom focus, **target files**)
|
||||
- Monitor completion via review-progress.json updates
|
||||
- TodoWrite updates: Mark dimensions as completed
|
||||
- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout)
|
||||
|
||||
**Phase 3: Aggregation**
|
||||
- Load all dimension JSON files from dimensions/
|
||||
- Calculate severity distribution: Count by critical/high/medium/low
|
||||
- Identify cross-cutting concerns: Files in 3+ dimensions
|
||||
- Select deep-dive findings: Critical + high in critical files (max 5)
|
||||
- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist
|
||||
- Update review-state.json with aggregation results
|
||||
|
||||
**Phase 4: Iteration Control**
|
||||
- Check iteration count < max_iterations (default 3)
|
||||
- Launch deep-dive agents for selected findings
|
||||
- Collect remediation plans and re-assessed severities
|
||||
- Update severity distribution based on re-assessments
|
||||
- Record iteration in review-state.json
|
||||
- Loop back to aggregation if still have critical/high findings
|
||||
|
||||
**Phase 5: Completion**
|
||||
- Generate REVIEW-SUMMARY.md with all findings and statistics
|
||||
- Update review-state.json with completion_time and phase=complete
|
||||
- TodoWrite completion: Mark all tasks done
|
||||
- Output: Dashboard path and REVIEW-SUMMARY.md path to user
|
||||
|
||||
### Review Agent (@cli-explore-agent)
|
||||
|
||||
**Analysis Mode**: Deep Scan (Phase 1: Bash structural + Phase 2: Gemini semantic + Phase 3: Synthesis)
|
||||
|
||||
**Context Provided by Orchestrator**:
|
||||
```javascript
|
||||
{
|
||||
dimension: "security|architecture|quality|...",
|
||||
review_type: "module",
|
||||
target_files: ["src/auth/service.ts", "src/auth/validator.ts", ...],
|
||||
output_paths: {
|
||||
json: "{output-dir}/dimensions/{dimension}.json",
|
||||
report: "{output-dir}/reports/{dimension}-analysis.md",
|
||||
cli_output: "{output-dir}/reports/{dimension}-cli-output.txt"
|
||||
},
|
||||
cli_config: {
|
||||
tool: "gemini",
|
||||
template: "~/.claude/workflows/cli-templates/prompts/analysis/xxx.txt",
|
||||
timeout: 3600000,
|
||||
mode: "analysis"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
1. Dimension JSON with findings array (see JSON Schema below)
|
||||
2. Analysis markdown report with summary and recommendations
|
||||
3. CLI output log for debugging
|
||||
|
||||
### Deep-Dive Agent (@cli-explore-agent)
|
||||
|
||||
**Analysis Mode**: Dependency Map + Deep Scan (for root cause analysis with architectural context)
|
||||
|
||||
**Context Provided**:
|
||||
```javascript
|
||||
{
|
||||
finding_id: "uuid",
|
||||
original_finding: {...},
|
||||
iteration: 1,
|
||||
output_paths: {
|
||||
json: "{output-dir}/iterations/iteration-1-finding-{uuid}.json",
|
||||
report: "{output-dir}/reports/deep-dive-1-{uuid}.md"
|
||||
},
|
||||
cli_config: {
|
||||
tool: "gemini",
|
||||
template: "01-diagnose-bug-root-cause.txt",
|
||||
timeout: 2400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
1. Deep-dive JSON with root cause, remediation plan, impact assessment
|
||||
2. Analysis report with detailed recommendations
|
||||
|
||||
## Dashboard Generation
|
||||
|
||||
### Mechanism
|
||||
|
||||
Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/templates/review-cycle-dashboard.html`, replaces placeholders, writes to output directory. Dashboard polls `review-progress.json` every 5 seconds for real-time updates, then loads all dimension JSON files when `phase=complete`.
|
||||
|
||||
**CRITICAL**: Dashboard MUST be generated in **Phase 1** to enable real-time progress monitoring throughout execution.
|
||||
|
||||
### Phase 1 Steps
|
||||
|
||||
1. **Read & Process Template**
|
||||
```javascript
|
||||
const template = Read('~/.claude/templates/review-cycle-dashboard.html');
|
||||
const dashboard = template
|
||||
.replace('{{SESSION_ID}}', `Module: ${pathPattern}`)
|
||||
.replace('{{REVIEW_TYPE}}', 'module');
|
||||
Write(`${outputDir}/dashboard.html`, dashboard);
|
||||
```
|
||||
|
||||
2. **Auto-open in Browser** (optional)
|
||||
```javascript
|
||||
Bash(`start ${dashboardPath}`); // Windows
|
||||
Bash(`open ${dashboardPath}`); // macOS
|
||||
Bash(`xdg-open ${dashboardPath}`); // Linux
|
||||
```
|
||||
|
||||
3. **Output Path to User**
|
||||
```
|
||||
📊 Dashboard: file://${absolutePath}/dashboard.html
|
||||
🔄 Monitor progress in real-time (auto-refresh every 5s)
|
||||
```
|
||||
|
||||
### Features Summary
|
||||
|
||||
- **Real-time Progress**: Phase indicator, progress bar, agent status (auto-refresh 5s)
|
||||
- **Interactive Findings**: Severity/dimension filtering, search, sort, detail drawer
|
||||
- **Export**: Generate markdown report
|
||||
- **Dark Mode**: Toggle with localStorage persistence
|
||||
|
||||
**Usage Details**: See `~/.claude/workflows/DASHBOARD-QUICKSTART.md`
|
||||
|
||||
## Reference
|
||||
|
||||
### CLI Tool Configuration
|
||||
|
||||
**Fallback Chain**: Gemini → Qwen → Codex (same as test-cycle-execute)
|
||||
|
||||
**Tool Details**:
|
||||
1. **Gemini** (primary): `gemini-2.5-pro` - 60min timeout
|
||||
2. **Qwen** (fallback): `coder-model` - 60min timeout
|
||||
3. **Codex** (fallback): `gpt-5.1-codex` - 60min timeout
|
||||
|
||||
**When to Fallback**: HTTP 429, timeout, invalid JSON output, confidence < 0.4
|
||||
|
||||
### Output File Structure
|
||||
|
||||
```
|
||||
{output-dir}/
|
||||
├── review-state.json # Orchestrator state machine
|
||||
├── review-progress.json # Real-time progress for dashboard
|
||||
├── dimensions/ # Per-dimension results
|
||||
│ ├── security.json
|
||||
│ ├── architecture.json
|
||||
│ ├── quality.json
|
||||
│ ├── action-items.json
|
||||
│ ├── performance.json
|
||||
│ ├── maintainability.json
|
||||
│ └── best-practices.json
|
||||
├── iterations/ # Deep-dive results
|
||||
│ ├── iteration-1-finding-{uuid}.json
|
||||
│ └── iteration-2-finding-{uuid}.json
|
||||
├── reports/ # Human-readable reports
|
||||
│ ├── security-analysis.md
|
||||
│ ├── security-cli-output.txt
|
||||
│ ├── deep-dive-1-{uuid}.md
|
||||
│ └── ...
|
||||
├── REVIEW-SUMMARY.md # Final summary
|
||||
└── dashboard.html # Interactive dashboard
|
||||
```
|
||||
|
||||
### Review State JSON
|
||||
|
||||
**Purpose**: Persisted state machine for phase transitions and iteration control - enables Resume
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"review_type": "module",
|
||||
"target_pattern": "src/auth/**",
|
||||
"resolved_files": [
|
||||
"src/auth/service.ts",
|
||||
"src/auth/validator.ts",
|
||||
"src/auth/middleware.ts"
|
||||
],
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"max_iterations": 3,
|
||||
"dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"selected_strategy": "comprehensive",
|
||||
"next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",
|
||||
"severity_distribution": {
|
||||
"critical": 2,
|
||||
"high": 5,
|
||||
"medium": 12,
|
||||
"low": 8
|
||||
},
|
||||
"critical_files": [...],
|
||||
"iterations": [...],
|
||||
"completion_criteria": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Review Progress JSON
|
||||
|
||||
**Purpose**: Real-time dashboard updates via polling
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"last_update": "2025-01-25T14:35:10Z",
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"progress": {
|
||||
"parallel_review": {
|
||||
"total_dimensions": 7,
|
||||
"completed": 5,
|
||||
"in_progress": 2,
|
||||
"percent_complete": 71
|
||||
},
|
||||
"deep_dive": {
|
||||
"total_findings": 6,
|
||||
"analyzed": 2,
|
||||
"in_progress": 1,
|
||||
"percent_complete": 33
|
||||
}
|
||||
},
|
||||
"agent_status": [
|
||||
{
|
||||
"agent_type": "review-agent",
|
||||
"dimension": "security",
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-25T14:30:00Z",
|
||||
"completed_at": "2025-01-25T15:15:00Z",
|
||||
"duration_ms": 2700000
|
||||
},
|
||||
{
|
||||
"agent_type": "deep-dive-agent",
|
||||
"finding_id": "sec-001-uuid",
|
||||
"status": "in_progress",
|
||||
"started_at": "2025-01-25T14:32:00Z"
|
||||
}
|
||||
],
|
||||
"estimated_completion": "2025-01-25T16:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Agent Output Schemas
|
||||
|
||||
**Agent-produced JSON files follow standardized schemas**:
|
||||
|
||||
1. **Dimension Results** (cli-explore-agent output from parallel reviews)
|
||||
- Schema: `~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json`
|
||||
- Output: `{output-dir}/dimensions/{dimension}.json`
|
||||
- Contains: findings array, summary statistics, cross_references
|
||||
|
||||
2. **Deep-Dive Results** (cli-explore-agent output from iterations)
|
||||
- Schema: `~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json`
|
||||
- Output: `{output-dir}/iterations/iteration-{N}-finding-{uuid}.json`
|
||||
- Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity
|
||||
|
||||
### Agent Invocation Template
|
||||
|
||||
**Review Agent** (parallel execution, 7 instances):
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
description=`Execute ${dimension} review analysis via Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for specified module files
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Deep Scan mode** for this review:
|
||||
- Phase 1: Bash structural scan for standard patterns (classes, functions, imports)
|
||||
- Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
|
||||
- Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read review state: ${reviewStateJsonPath}
|
||||
2. Get target files: Read resolved_files from review-state.json
|
||||
3. Validate file access: bash(ls -la ${targetFiles.join(' ')})
|
||||
|
||||
## Review Context
|
||||
- Review Type: module (independent)
|
||||
- Review Dimension: ${dimension}
|
||||
- Review ID: ${reviewId}
|
||||
- Target Pattern: ${targetPattern}
|
||||
- Resolved Files: ${resolvedFiles.length} files
|
||||
- Output Directory: ${outputDir}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex (fallback chain)
|
||||
- Template: ~/.claude/workflows/cli-templates/prompts/analysis/${dimensionTemplate}
|
||||
- Custom Focus: ${customFocus || 'Standard dimension analysis'}
|
||||
- Timeout: ${timeout}ms
|
||||
- Mode: analysis (READ-ONLY)
|
||||
- Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')}
|
||||
|
||||
## Expected Deliverables
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
|
||||
- MUST include: findings array with severity, file, line, description, recommendation
|
||||
- MUST include: summary statistics (total findings, severity distribution)
|
||||
- MUST include: cross_references to related findings
|
||||
2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md
|
||||
- Human-readable summary with recommendations
|
||||
- Grouped by severity: critical → high → medium → low
|
||||
- Include file:line references for all findings
|
||||
3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt
|
||||
- Raw CLI tool output for debugging
|
||||
- Include full analysis text
|
||||
|
||||
## Dimension-Specific Guidance
|
||||
${getDimensionGuidance(dimension)}
|
||||
|
||||
## Success Criteria
|
||||
- All target files analyzed for ${dimension} concerns
|
||||
- All findings include file:line references with code snippets
|
||||
- Severity assessment follows established criteria (see reference)
|
||||
- Recommendations are actionable with code examples
|
||||
- JSON output is valid and follows schema exactly
|
||||
- Report is comprehensive and well-organized
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Deep-Dive Agent** (iteration execution):
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Dependency Map mode** first to understand dependencies:
|
||||
- Build dependency graph around ${file} to identify affected components
|
||||
- Detect circular dependencies or tight coupling related to this finding
|
||||
- Calculate change risk scores for remediation impact
|
||||
|
||||
Then apply **Deep Scan mode** for semantic analysis:
|
||||
- Understand design intent and architectural context
|
||||
- Identify non-standard patterns or implicit dependencies
|
||||
- Extract remediation insights from code structure
|
||||
|
||||
## Finding Context
|
||||
- Finding ID: ${findingId}
|
||||
- Original Dimension: ${dimension}
|
||||
- Title: ${findingTitle}
|
||||
- File: ${file}:${line}
|
||||
- Severity: ${severity}
|
||||
- Category: ${category}
|
||||
- Original Description: ${description}
|
||||
- Iteration: ${iteration}
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read original finding: ${dimensionJsonPath}
|
||||
2. Read affected file: ${file}
|
||||
3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
|
||||
4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
- Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
|
||||
- Timeout: 2400000ms (40 minutes)
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
|
||||
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
|
||||
- MUST include: root_cause with summary, details, affected_scope, similar_patterns
|
||||
- MUST include: remediation_plan with approach, steps[], estimated_effort, risk_level
|
||||
- MUST include: impact_assessment with files_affected, tests_required, breaking_changes
|
||||
- MUST include: reassessed_severity with severity_change_reason
|
||||
- MUST include: confidence_score (0.0-1.0)
|
||||
2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md
|
||||
- Detailed root cause analysis
|
||||
- Step-by-step remediation plan
|
||||
- Impact assessment and rollback strategy
|
||||
|
||||
## Success Criteria
|
||||
- Root cause clearly identified with supporting evidence
|
||||
- Remediation plan is step-by-step actionable with exact file:line references
|
||||
- Each step includes specific commands and validation tests
|
||||
- Impact fully assessed (files, tests, breaking changes, dependencies)
|
||||
- Severity re-evaluation justified with evidence
|
||||
- Confidence score accurately reflects certainty of analysis
|
||||
- References include project-specific and external documentation
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Dimension Guidance Reference
|
||||
|
||||
```javascript
|
||||
function getDimensionGuidance(dimension) {
|
||||
const guidance = {
|
||||
security: `
|
||||
Focus Areas:
|
||||
- Input validation and sanitization
|
||||
- Authentication and authorization mechanisms
|
||||
- Data encryption (at-rest and in-transit)
|
||||
- SQL/NoSQL injection vulnerabilities
|
||||
- XSS, CSRF, and other web vulnerabilities
|
||||
- Sensitive data exposure
|
||||
- Access control and privilege escalation
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure
|
||||
- High: Missing authorization checks, weak encryption, exposed secrets
|
||||
- Medium: Missing input validation, insecure defaults, weak password policies
|
||||
- Low: Security headers missing, verbose error messages, outdated dependencies
|
||||
`,
|
||||
architecture: `
|
||||
Focus Areas:
|
||||
- Layering and separation of concerns
|
||||
- Coupling and cohesion
|
||||
- Design pattern adherence
|
||||
- Dependency management
|
||||
- Scalability and extensibility
|
||||
- Module boundaries
|
||||
- API design consistency
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Circular dependencies, god objects, tight coupling across layers
|
||||
- High: Violated architectural principles, scalability bottlenecks
|
||||
- Medium: Missing abstractions, inconsistent patterns, suboptimal design
|
||||
- Low: Minor coupling issues, documentation gaps, naming inconsistencies
|
||||
`,
|
||||
quality: `
|
||||
Focus Areas:
|
||||
- Code duplication
|
||||
- Complexity (cyclomatic, cognitive)
|
||||
- Naming conventions
|
||||
- Error handling patterns
|
||||
- Code readability
|
||||
- Comment quality
|
||||
- Dead code
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Severe complexity (CC > 20), massive duplication (>50 lines)
|
||||
- High: High complexity (CC > 10), significant duplication, poor error handling
|
||||
- Medium: Moderate complexity (CC > 5), naming issues, code smells
|
||||
- Low: Minor duplication, documentation gaps, cosmetic issues
|
||||
`,
|
||||
'action-items': `
|
||||
Focus Areas:
|
||||
- Requirements coverage verification
|
||||
- Acceptance criteria met
|
||||
- Documentation completeness
|
||||
- Deployment readiness
|
||||
- Missing functionality
|
||||
- Test coverage gaps
|
||||
- Configuration management
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Core requirements not met, deployment blockers
|
||||
- High: Significant functionality missing, acceptance criteria not met
|
||||
- Medium: Minor requirements gaps, documentation incomplete
|
||||
- Low: Nice-to-have features missing, minor documentation gaps
|
||||
`,
|
||||
performance: `
|
||||
Focus Areas:
|
||||
- N+1 query problems
|
||||
- Inefficient algorithms (O(n²) where O(n log n) possible)
|
||||
- Memory leaks
|
||||
- Blocking operations on main thread
|
||||
- Missing caching opportunities
|
||||
- Resource usage (CPU, memory, network)
|
||||
- Database query optimization
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Memory leaks, O(n²) in hot path, blocking main thread
|
||||
- High: N+1 queries, missing indexes, inefficient algorithms
|
||||
- Medium: Suboptimal caching, unnecessary computations, lazy loading issues
|
||||
- Low: Minor optimization opportunities, redundant operations
|
||||
`,
|
||||
maintainability: `
|
||||
Focus Areas:
|
||||
- Technical debt indicators
|
||||
- Magic numbers and hardcoded values
|
||||
- Long methods (>50 lines)
|
||||
- Large classes (>500 lines)
|
||||
- Dead code and commented code
|
||||
- Code documentation
|
||||
- Test coverage
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Massive methods (>200 lines), severe technical debt blocking changes
|
||||
- High: Large methods (>100 lines), significant dead code, undocumented complex logic
|
||||
- Medium: Magic numbers, moderate technical debt, missing tests
|
||||
- Low: Minor refactoring opportunities, cosmetic improvements
|
||||
`,
|
||||
'best-practices': `
|
||||
Focus Areas:
|
||||
- Framework conventions adherence
|
||||
- Language idioms
|
||||
- Anti-patterns
|
||||
- Deprecated API usage
|
||||
- Coding standards compliance
|
||||
- Error handling patterns
|
||||
- Logging and monitoring
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Severe anti-patterns, deprecated APIs with security risks
|
||||
- High: Major convention violations, poor error handling, missing logging
|
||||
- Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns
|
||||
- Low: Cosmetic style issues, minor convention deviations
|
||||
`
|
||||
};
|
||||
|
||||
return guidance[dimension] || 'Standard code review analysis';
|
||||
}
|
||||
```
|
||||
|
||||
### Completion Conditions
|
||||
|
||||
**Full Success**:
|
||||
- All dimensions reviewed
|
||||
- Critical findings = 0
|
||||
- High findings ≤ 5
|
||||
- Action: Generate final report, mark phase=complete
|
||||
|
||||
**Partial Success**:
|
||||
- All dimensions reviewed
|
||||
- Max iterations reached
|
||||
- Still have critical/high findings
|
||||
- Action: Generate report with warnings, recommend follow-up
|
||||
|
||||
**Resume Capability**:
|
||||
- Read review-state.json on startup
|
||||
- Check phase and next_action
|
||||
- Resume from current phase (parallel/aggregate/iterate)
|
||||
- Preserve iteration history
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| Invalid path pattern | Error: Provide valid glob pattern or file path |
|
||||
| No files matched | Error: Pattern matched 0 files, check path |
|
||||
| Files not readable | Error: Permission denied for specified files |
|
||||
| CLI analysis failure | Fallback: Gemini → Qwen → Codex → degraded mode |
|
||||
| Invalid JSON output | Retry with clarified prompt, fallback to next tool |
|
||||
| Max iterations reached | Generate report with remaining issues, mark partial success |
|
||||
| Agent timeout | Log timeout, continue with available results |
|
||||
| Missing dimension file | Skip in aggregation, log warning |
|
||||
|
||||
**CLI Fallback Triggers** (same as test-cycle-execute):
|
||||
1. Invalid JSON output (parse error, missing required fields)
|
||||
2. Low confidence score < 0.4
|
||||
3. HTTP 429, 5xx errors, timeouts
|
||||
4. Analysis too brief (< 100 words in report)
|
||||
|
||||
### TodoWrite Structure
|
||||
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{
|
||||
content: "Phase 1: Discovery & Initialization",
|
||||
status: "completed",
|
||||
activeForm: "Completed discovery & initialization"
|
||||
},
|
||||
{
|
||||
content: "Phase 2: Parallel Reviews (7 dimensions)",
|
||||
status: "in_progress",
|
||||
activeForm: "Executing parallel reviews"
|
||||
},
|
||||
{
|
||||
content: " → Security review (src/auth/**)",
|
||||
status: "completed",
|
||||
activeForm: "Analyzing security"
|
||||
},
|
||||
{
|
||||
content: " → Architecture review (src/auth/**)",
|
||||
status: "completed",
|
||||
activeForm: "Analyzing architecture"
|
||||
},
|
||||
// ... (same pattern as review-session-cycle)
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start Specific**: Begin with focused module patterns for faster results
|
||||
2. **Expand Gradually**: Add more modules based on initial findings
|
||||
3. **Use Glob Wisely**: `src/auth/**` is more efficient than `src/**` with lots of irrelevant files
|
||||
4. **Trust Aggregation Logic**: Auto-selection based on proven heuristics
|
||||
5. **Monitor Logs**: Check reports/ directory for CLI analysis insights
|
||||
6. **Dashboard Polling**: Refresh every 5 seconds for real-time updates
|
||||
7. **Resume Support**: Interrupted reviews can resume from last checkpoint
|
||||
8. **Export Results**: Use dashboard export for external tracking tools
|
||||
|
||||
## Examples
|
||||
|
||||
### Review Authentication Module
|
||||
```bash
|
||||
/workflow:review-module-cycle src/auth/**
|
||||
```
|
||||
|
||||
### Review Payment Processing with Security Focus
|
||||
```bash
|
||||
/workflow:review-module-cycle src/payment/** --dimensions=security,architecture
|
||||
```
|
||||
|
||||
### Review Multiple Modules
|
||||
```bash
|
||||
/workflow:review-module-cycle src/auth/**,src/payment/**,src/user/**
|
||||
```
|
||||
|
||||
### Review Specific Critical Files
|
||||
```bash
|
||||
/workflow:review-module-cycle src/payment/processor.ts,src/auth/validator.ts --max-iterations=5
|
||||
```
|
||||
@@ -1,31 +1,32 @@
|
||||
---
|
||||
name: review-cycle
|
||||
description: Comprehensive multi-dimensional code review with hybrid parallel-iterative execution. Analyzes code across 7 dimensions, aggregates findings, and performs focused deep-dives on critical issues until quality gates met.
|
||||
name: review-session-cycle
|
||||
description: Session-based comprehensive multi-dimensional code review. Analyzes git changes from workflow session across 7 dimensions with hybrid parallel-iterative execution, aggregates findings, and performs focused deep-dives on critical issues until quality gates met.
|
||||
argument-hint: "[session-id] [--dimensions=security,architecture,...] [--max-iterations=N] [--output-dir=path] [--resume]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
|
||||
---
|
||||
|
||||
# Workflow Review-Cycle Command
|
||||
# Workflow Review-Session-Cycle Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Execute comprehensive review (all 7 dimensions)
|
||||
/workflow:review-cycle
|
||||
# Execute comprehensive session review (all 7 dimensions)
|
||||
/workflow:review-session-cycle
|
||||
|
||||
# Custom dimensions selection
|
||||
/workflow:review-cycle --dimensions=security,architecture,quality
|
||||
# Review specific session with custom dimensions
|
||||
/workflow:review-session-cycle WFS-payment-integration --dimensions=security,architecture,quality
|
||||
|
||||
# Resume interrupted review
|
||||
/workflow:review-cycle --resume
|
||||
/workflow:review-session-cycle --resume
|
||||
|
||||
# Specify session and iteration limit
|
||||
/workflow:review-cycle WFS-payment-integration --max-iterations=5
|
||||
/workflow:review-session-cycle WFS-payment-integration --max-iterations=5
|
||||
|
||||
# Custom output directory
|
||||
/workflow:review-cycle --output-dir=.workflow/active/WFS-session/.review-cycle
|
||||
/workflow:review-session-cycle --output-dir=.workflow/active/WFS-session/.review-cycle
|
||||
```
|
||||
|
||||
**Review Scope**: Git changes from session creation to present (via `git log --since`)
|
||||
**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
|
||||
**Max Iterations**: 3 (default, adjustable)
|
||||
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
|
||||
@@ -33,11 +34,15 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
Multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment.
|
||||
Session-based multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **git changes within a workflow session**.
|
||||
|
||||
**Review Scope**:
|
||||
- **Session-based**: Reviews only files changed during the workflow session (via `git log --since="${sessionCreatedAt}"`)
|
||||
- **For independent module review**: Use `/workflow:review-module-cycle` command instead
|
||||
|
||||
**vs Standard Review**:
|
||||
- **Standard**: Sequential manual reviews → Inconsistent coverage → Missed cross-cutting concerns
|
||||
- **Review-Cycle**: **Parallel automated analysis → Aggregate findings → Deep-dive critical issues** → Comprehensive coverage
|
||||
- **Review-Session-Cycle**: **Parallel automated analysis → Aggregate findings → Deep-dive critical issues** → Comprehensive coverage
|
||||
|
||||
### Value Proposition
|
||||
1. **Comprehensive Coverage**: 7 specialized dimensions analyze all quality aspects simultaneously
|
||||
Reference in New Issue
Block a user