mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
feat: Implement phases 6 to 9 of the review cycle fix process, including discovery, batching, parallel planning, execution, and completion
- Added Phase 6: Fix Discovery & Batching with intelligent grouping and batching of findings. - Added Phase 7: Fix Parallel Planning to launch planning agents for concurrent analysis and aggregation of partial plans. - Added Phase 8: Fix Execution for stage-based execution of fixes with conservative test verification. - Added Phase 9: Fix Completion to aggregate results, generate summary reports, and handle session completion. - Introduced new frontend components: ResizeHandle for draggable resizing of sidebar panels and useResizablePanel hook for managing panel sizes with localStorage persistence. - Added PowerShell script for checking TypeScript errors in source code, excluding test files.
This commit is contained in:
catlog22
412
.codex/skills/review-cycle/SKILL.md
Normal file
412
.codex/skills/review-cycle/SKILL.md
Normal file
@@ -0,0 +1,412 @@
|
||||
---
|
||||
name: review-cycle
|
||||
description: Unified multi-dimensional code review with automated fix orchestration. Supports session-based (git changes) and module-based (path patterns) review modes with 7-dimension parallel analysis, iterative deep-dive, and automated fix pipeline. Triggers on "workflow:review-cycle", "workflow:review-session-cycle", "workflow:review-module-cycle", "workflow:review-cycle-fix".
|
||||
allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep
|
||||
---
|
||||
|
||||
# Review Cycle
|
||||
|
||||
Unified multi-dimensional code review orchestrator with dual-mode (session/module) file discovery, 7-dimension parallel analysis, iterative deep-dive on critical findings, and optional automated fix pipeline with intelligent batching and parallel planning.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────┐
|
||||
│ Review Cycle Orchestrator (SKILL.md) │
|
||||
│ → Pure coordinator: mode detection, phase dispatch, state tracking │
|
||||
└───────────────────────────────┬──────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────┼─────────────────────────────────┐
|
||||
│ Review Pipeline (Phase 1-5) │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ │ Phase 1 │→ │ Phase 2 │→ │ Phase 3 │→ │ Phase 4 │→ │ Phase 5 │
|
||||
│ │Discovery│ │Parallel │ │Aggregate│ │Deep-Dive│ │Complete │
|
||||
│ │ Init │ │ Review │ │ │ │(cond.) │ │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
│ session| 7 agents severity N agents finalize
|
||||
│ module ×cli-explore calc ×cli-explore state
|
||||
│ ↕ loop
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
(optional --fix)
|
||||
│
|
||||
┌─────────────────────────────┼─────────────────────────────────┐
|
||||
│ Fix Pipeline (Phase 6-9) │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ │ Phase 6 │→ │ Phase 7 │→ │ Phase 8 │→ │ Phase 9 │
|
||||
│ │Discovery│ │Parallel │ │Execution│ │Complete │
|
||||
│ │Batching │ │Planning │ │Orchestr.│ │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
│ grouping N agents M agents aggregate
|
||||
│ + batch ×cli-plan ×cli-exec + summary
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **Dual-Mode Review**: Session-based (git changes) and module-based (path patterns) share the same review pipeline (Phase 2-5), differing only in file discovery (Phase 1)
|
||||
2. **Pure Orchestrator**: Execute phases in sequence, parse outputs, pass context between them
|
||||
3. **Progressive Phase Loading**: Phase docs are read on-demand when that phase executes, not all at once
|
||||
4. **Auto-Continue**: All phases run autonomously without user intervention between phases
|
||||
5. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent
|
||||
6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS
|
||||
7. **Optional Fix Pipeline**: Phase 6-9 triggered only by explicit `--fix` flag or user confirmation after Phase 5
|
||||
8. **Content Preservation**: All agent prompts, code, schemas preserved verbatim from source commands
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
# Review Pipeline (Phase 1-5)
|
||||
review-cycle <path-pattern> # Module mode
|
||||
review-cycle [session-id] # Session mode
|
||||
review-cycle [session-id|path-pattern] [FLAGS] # With flags
|
||||
|
||||
# Fix Pipeline (Phase 6-9)
|
||||
review-cycle --fix <review-dir|export-file> # Fix mode
|
||||
review-cycle --fix <review-dir> [FLAGS] # Fix with flags
|
||||
|
||||
# Flags
|
||||
--dimensions=dim1,dim2,... Custom dimensions (default: all 7)
|
||||
--max-iterations=N Max deep-dive iterations (default: 3)
|
||||
--fix Enter fix pipeline after review or standalone
|
||||
--resume Resume interrupted fix session
|
||||
--batch-size=N Findings per planning batch (default: 5, fix mode only)
|
||||
|
||||
# Examples
|
||||
review-cycle src/auth/** # Module: review auth
|
||||
review-cycle src/auth/**,src/payment/** # Module: multiple paths
|
||||
review-cycle src/auth/** --dimensions=security,architecture # Module: custom dims
|
||||
review-cycle WFS-payment-integration # Session: specific
|
||||
review-cycle # Session: auto-detect
|
||||
review-cycle --fix .workflow/active/WFS-123/.review/ # Fix: from review dir
|
||||
review-cycle --fix --resume # Fix: resume session
|
||||
```
|
||||
|
||||
## Mode Detection
|
||||
|
||||
```javascript
|
||||
// Input parsing logic (orchestrator responsibility)
|
||||
function detectMode(args) {
|
||||
if (args.includes('--fix')) return 'fix';
|
||||
if (args.match(/\*|\.ts|\.js|\.py|src\/|lib\//)) return 'module'; // glob/path patterns
|
||||
if (args.match(/^WFS-/) || args.trim() === '') return 'session'; // session ID or empty
|
||||
return 'session'; // default
|
||||
}
|
||||
```
|
||||
|
||||
| Input Pattern | Detected Mode | Phase Entry |
|
||||
|---------------|---------------|-------------|
|
||||
| `src/auth/**` | `module` | Phase 1 (module branch) |
|
||||
| `WFS-payment-integration` | `session` | Phase 1 (session branch) |
|
||||
| _(empty)_ | `session` | Phase 1 (session branch, auto-detect) |
|
||||
| `--fix .review/` | `fix` | Phase 6 |
|
||||
| `--fix --resume` | `fix` | Phase 6 (resume) |
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
└─ Detect mode (session|module|fix) → route to appropriate phase entry
|
||||
|
||||
Review Pipeline (session or module mode):
|
||||
|
||||
Phase 1: Discovery & Initialization
|
||||
└─ Ref: phases/01-discovery-initialization.md
|
||||
├─ Session mode: session discovery → git changed files → resolve
|
||||
├─ Module mode: path patterns → glob expand → resolve
|
||||
└─ Common: create session, output dirs, review-state.json, review-progress.json
|
||||
|
||||
Phase 2: Parallel Review Coordination
|
||||
└─ Ref: phases/02-parallel-review.md
|
||||
├─ Spawn 7 cli-explore-agent instances (Deep Scan mode)
|
||||
├─ Each produces dimensions/{dimension}.json + reports/{dimension}-analysis.md
|
||||
├─ Lifecycle: spawn_agent → batch wait → close_agent
|
||||
└─ CLI fallback: Gemini → Qwen → Codex
|
||||
|
||||
Phase 3: Aggregation
|
||||
└─ Ref: phases/03-aggregation.md
|
||||
├─ Load dimension JSONs, calculate severity distribution
|
||||
├─ Identify cross-cutting concerns (files in 3+ dimensions)
|
||||
└─ Decision: critical > 0 OR high > 5 OR critical files → Phase 4
|
||||
Else → Phase 5
|
||||
|
||||
Phase 4: Iterative Deep-Dive (conditional)
|
||||
└─ Ref: phases/04-iterative-deep-dive.md
|
||||
├─ Select critical findings (max 5 per iteration)
|
||||
├─ Spawn deep-dive agents for root cause analysis
|
||||
├─ Re-assess severity → loop back to Phase 3 aggregation
|
||||
└─ Exit when: no critical findings OR max iterations reached
|
||||
|
||||
Phase 5: Review Completion
|
||||
└─ Ref: phases/05-review-completion.md
|
||||
├─ Finalize review-state.json + review-progress.json
|
||||
├─ Prompt user: "Run automated fixes? [Y/n]"
|
||||
└─ If yes → Continue to Phase 6
|
||||
|
||||
Fix Pipeline (--fix mode or after Phase 5):
|
||||
|
||||
Phase 6: Fix Discovery & Batching
|
||||
└─ Ref: phases/06-fix-discovery-batching.md
|
||||
├─ Validate export file, create fix session
|
||||
└─ Intelligent grouping by file+dimension similarity → batches
|
||||
|
||||
Phase 7: Fix Parallel Planning
|
||||
└─ Ref: phases/07-fix-parallel-planning.md
|
||||
├─ Spawn N cli-planning-agent instances (≤10 parallel)
|
||||
├─ Each outputs partial-plan-{batch-id}.json
|
||||
├─ Lifecycle: spawn_agent → batch wait → close_agent
|
||||
└─ Orchestrator aggregates → fix-plan.json
|
||||
|
||||
Phase 8: Fix Execution
|
||||
└─ Ref: phases/08-fix-execution.md
|
||||
├─ Stage-based execution per aggregated timeline
|
||||
├─ Each group: analyze → fix → test → commit/rollback
|
||||
├─ Lifecycle: spawn_agent → wait → close_agent per group
|
||||
└─ 100% test pass rate required
|
||||
|
||||
Phase 9: Fix Completion
|
||||
└─ Ref: phases/09-fix-completion.md
|
||||
├─ Aggregate results → fix-summary.md
|
||||
└─ Optional: complete workflow session if all fixes successful
|
||||
|
||||
Complete: Review reports + optional fix results
|
||||
```
|
||||
|
||||
**Phase Reference Documents** (read on-demand when phase executes):
|
||||
|
||||
| Phase | Document | Load When | Source |
|
||||
|-------|----------|-----------|--------|
|
||||
| 1 | [phases/01-discovery-initialization.md](phases/01-discovery-initialization.md) | Review/Fix start | review-session-cycle + review-module-cycle Phase 1 (fused) |
|
||||
| 2 | [phases/02-parallel-review.md](phases/02-parallel-review.md) | Phase 1 complete | Shared from both review commands Phase 2 |
|
||||
| 3 | [phases/03-aggregation.md](phases/03-aggregation.md) | Phase 2 complete | Shared from both review commands Phase 3 |
|
||||
| 4 | [phases/04-iterative-deep-dive.md](phases/04-iterative-deep-dive.md) | Aggregation triggers iteration | Shared from both review commands Phase 4 |
|
||||
| 5 | [phases/05-review-completion.md](phases/05-review-completion.md) | No more iterations needed | Shared from both review commands Phase 5 |
|
||||
| 6 | [phases/06-fix-discovery-batching.md](phases/06-fix-discovery-batching.md) | Fix mode entry | review-cycle-fix Phase 1 + 1.5 |
|
||||
| 7 | [phases/07-fix-parallel-planning.md](phases/07-fix-parallel-planning.md) | Phase 6 complete | review-cycle-fix Phase 2 |
|
||||
| 8 | [phases/08-fix-execution.md](phases/08-fix-execution.md) | Phase 7 complete | review-cycle-fix Phase 3 |
|
||||
| 9 | [phases/09-fix-completion.md](phases/09-fix-completion.md) | Phase 8 complete | review-cycle-fix Phase 4 + 5 |
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is progress tracking initialization, second action is Phase 1 execution
|
||||
2. **Mode Detection First**: Parse input to determine session/module/fix mode before Phase 1
|
||||
3. **Parse Every Output**: Extract required data from each phase for next phase
|
||||
4. **Auto-Continue**: Check progress status to execute next pending phase automatically
|
||||
5. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
|
||||
6. **DO NOT STOP**: Continuous multi-phase workflow until all applicable phases complete
|
||||
7. **Conditional Phase 4**: Only execute if aggregation triggers iteration (critical > 0 OR high > 5 OR critical files)
|
||||
8. **Fix Pipeline Optional**: Phase 6-9 only execute with explicit --fix flag or user confirmation
|
||||
9. **Explicit Lifecycle**: Always close_agent after wait completes to free resources
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
User Input (path-pattern | session-id | --fix export-file)
|
||||
↓
|
||||
[Mode Detection: session | module | fix]
|
||||
↓
|
||||
Phase 1: Discovery & Initialization
|
||||
↓ Output: sessionId, reviewId, resolvedFiles, reviewMode, outputDir
|
||||
↓ review-state.json, review-progress.json
|
||||
Phase 2: Parallel Review Coordination
|
||||
↓ Output: dimensions/*.json, reports/*-analysis.md
|
||||
Phase 3: Aggregation
|
||||
↓ Output: severityDistribution, criticalFiles, deepDiveFindings
|
||||
↓ Decision: iterate? → Phase 4 : Phase 5
|
||||
Phase 4: Iterative Deep-Dive (conditional, loops with Phase 3)
|
||||
↓ Output: iterations/*.json, reports/deep-dive-*.md
|
||||
↓ Loop: re-aggregate → check criteria → iterate or exit
|
||||
Phase 5: Review Completion
|
||||
↓ Output: final review-state.json, review-progress.json
|
||||
↓ Decision: fix? → Phase 6 : END
|
||||
Phase 6: Fix Discovery & Batching
|
||||
↓ Output: finding batches (in-memory)
|
||||
Phase 7: Fix Parallel Planning
|
||||
↓ Output: partial-plan-*.json → fix-plan.json (aggregated)
|
||||
Phase 8: Fix Execution
|
||||
↓ Output: fix-progress-*.json, git commits
|
||||
Phase 9: Fix Completion
|
||||
↓ Output: fix-summary.md, fix-history.json
|
||||
```
|
||||
|
||||
## Subagent API Reference
|
||||
|
||||
### spawn_agent
|
||||
|
||||
Create a new subagent with task assignment.
|
||||
|
||||
```javascript
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## TASK CONTEXT
|
||||
${taskContext}
|
||||
|
||||
## DELIVERABLES
|
||||
${deliverables}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### wait
|
||||
|
||||
Get results from subagent (only way to retrieve results).
|
||||
|
||||
```javascript
|
||||
const result = wait({
|
||||
ids: [agentId],
|
||||
timeout_ms: 600000 // 10 minutes
|
||||
})
|
||||
|
||||
if (result.timed_out) {
|
||||
// Handle timeout - can continue waiting or send_input to prompt completion
|
||||
}
|
||||
|
||||
// Check completion status
|
||||
if (result.status[agentId].completed) {
|
||||
const output = result.status[agentId].completed;
|
||||
}
|
||||
```
|
||||
|
||||
### send_input
|
||||
|
||||
Continue interaction with active subagent (for clarification or follow-up).
|
||||
|
||||
```javascript
|
||||
send_input({
|
||||
id: agentId,
|
||||
message: `
|
||||
## CLARIFICATION ANSWERS
|
||||
${answers}
|
||||
|
||||
## NEXT STEP
|
||||
Continue with analysis generation.
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### close_agent
|
||||
|
||||
Clean up subagent resources (irreversible).
|
||||
|
||||
```javascript
|
||||
close_agent({ id: agentId })
|
||||
```
|
||||
|
||||
## Progress Tracking Pattern
|
||||
|
||||
**Review Pipeline Initialization**:
|
||||
```
|
||||
Phase 1: Discovery & Initialization → pending
|
||||
Phase 2: Parallel Reviews (7 dimensions) → pending
|
||||
Phase 3: Aggregation → pending
|
||||
Phase 4: Deep-dive (conditional) → pending
|
||||
Phase 5: Review Completion → pending
|
||||
```
|
||||
|
||||
**During Phase 2 (sub-tasks for each dimension)**:
|
||||
```
|
||||
→ Security review → in_progress / completed
|
||||
→ Architecture review → in_progress / completed
|
||||
→ Quality review → in_progress / completed
|
||||
... other dimensions
|
||||
```
|
||||
|
||||
**Fix Pipeline (added after Phase 5 if triggered)**:
|
||||
```
|
||||
Phase 6: Fix Discovery & Batching → pending
|
||||
Phase 7: Parallel Planning → pending
|
||||
Phase 8: Execution → pending
|
||||
Phase 9: Fix Completion → pending
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Review Pipeline Errors
|
||||
|
||||
| Phase | Error | Blocking? | Action |
|
||||
|-------|-------|-----------|--------|
|
||||
| Phase 1 | Session not found (session mode) | Yes | Error and exit |
|
||||
| Phase 1 | No changed files (session mode) | Yes | Error and exit |
|
||||
| Phase 1 | Invalid path pattern (module mode) | Yes | Error and exit |
|
||||
| Phase 1 | No files matched (module mode) | Yes | Error and exit |
|
||||
| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
|
||||
| Phase 2 | All dimensions fail | Yes | Error and exit |
|
||||
| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
|
||||
| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
|
||||
| Phase 4 | Max iterations reached | No | Generate partial report |
|
||||
|
||||
### Fix Pipeline Errors
|
||||
|
||||
| Phase | Error | Blocking? | Action |
|
||||
|-------|-------|-----------|--------|
|
||||
| Phase 6 | Invalid export file | Yes | Abort with error |
|
||||
| Phase 6 | Empty batches | No | Warn and skip empty |
|
||||
| Phase 7 | Planning agent timeout | No | Mark batch failed, continue others |
|
||||
| Phase 7 | All agents fail | Yes | Abort fix session |
|
||||
| Phase 8 | Test failure after fix | No | Rollback, retry up to max_iterations |
|
||||
| Phase 8 | Git operations fail | Yes | Abort, preserve state |
|
||||
| Phase 9 | Aggregation error | No | Generate partial summary |
|
||||
|
||||
### CLI Fallback Chain
|
||||
|
||||
Gemini → Qwen → Codex → degraded mode
|
||||
|
||||
**Fallback Triggers**: HTTP 429/5xx, connection timeout, invalid JSON output, low confidence < 0.4, analysis too brief (< 100 words)
|
||||
|
||||
## Output File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── review-state.json # Orchestrator state machine
|
||||
├── review-progress.json # Real-time progress
|
||||
├── dimensions/ # Per-dimension results (Phase 2)
|
||||
│ ├── security.json
|
||||
│ ├── architecture.json
|
||||
│ ├── quality.json
|
||||
│ ├── action-items.json
|
||||
│ ├── performance.json
|
||||
│ ├── maintainability.json
|
||||
│ └── best-practices.json
|
||||
├── iterations/ # Deep-dive results (Phase 4)
|
||||
│ ├── 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
|
||||
│ └── ...
|
||||
└── fixes/{fix-session-id}/ # Fix results (Phase 6-9)
|
||||
├── partial-plan-*.json
|
||||
├── fix-plan.json
|
||||
├── fix-progress-*.json
|
||||
├── fix-summary.md
|
||||
├── active-fix-session.json
|
||||
└── fix-history.json
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
### View Progress
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
|
||||
### Workflow Pipeline
|
||||
```bash
|
||||
# Step 1: Review (this skill)
|
||||
review-cycle src/auth/**
|
||||
|
||||
# Step 2: Fix (continue or standalone)
|
||||
review-cycle --fix .workflow/active/WFS-{session-id}/.review/
|
||||
```
|
||||
341
.codex/skills/review-cycle/phases/01-discovery-initialization.md
Normal file
341
.codex/skills/review-cycle/phases/01-discovery-initialization.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# Phase 1: Discovery & Initialization
|
||||
|
||||
> Source: Fused from `commands/workflow/review-session-cycle.md` Phase 1 + `commands/workflow/review-module-cycle.md` Phase 1
|
||||
|
||||
## Overview
|
||||
|
||||
Detect review mode (session or module), resolve target files, create workflow session, initialize output directory structure and state files.
|
||||
|
||||
## Mode Detection
|
||||
|
||||
The review mode is determined by the input arguments:
|
||||
|
||||
- **Session mode**: No path pattern provided, OR a `WFS-*` session ID is provided. Reviews all changes within an existing workflow session (git-based change detection).
|
||||
- **Module mode**: Glob/path patterns are provided (e.g., `src/auth/**`, `src/payment/processor.ts`). Reviews specific files/directories regardless of session history.
|
||||
|
||||
---
|
||||
|
||||
## Session Mode (review-session-cycle)
|
||||
|
||||
### Step 1.1: Session Discovery
|
||||
|
||||
```javascript
|
||||
// If session ID not provided, auto-detect
|
||||
if (!providedSessionId) {
|
||||
// Check for active sessions
|
||||
const activeSessions = Glob('.workflow/active/WFS-*');
|
||||
if (activeSessions.length === 1) {
|
||||
sessionId = activeSessions[0].match(/WFS-[^/]+/)[0];
|
||||
} else if (activeSessions.length > 1) {
|
||||
// List sessions and prompt user
|
||||
error("Multiple active sessions found. Please specify session ID.");
|
||||
} else {
|
||||
error("No active session found. Create session first.");
|
||||
}
|
||||
} else {
|
||||
sessionId = providedSessionId;
|
||||
}
|
||||
|
||||
// Validate session exists
|
||||
Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`);
|
||||
```
|
||||
|
||||
### Step 1.2: Session Validation
|
||||
|
||||
- Ensure session has implementation artifacts (check `.summaries/` or `.task/` directory)
|
||||
- Extract session creation timestamp from `workflow-session.json`
|
||||
- Use timestamp for git log filtering: `git log --since="${sessionCreatedAt}"`
|
||||
|
||||
### Step 1.3: Changed Files Detection
|
||||
|
||||
```bash
|
||||
# Get files changed since session creation
|
||||
git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Mode (review-module-cycle)
|
||||
|
||||
### Step 1.1: Session Creation
|
||||
|
||||
```javascript
|
||||
// Create workflow session for this review (type: review)
|
||||
// Orchestrator handles session creation directly
|
||||
Bash(`mkdir -p .workflow/active/WFS-review-${Date.now()}`);
|
||||
|
||||
// Initialize workflow-session.json
|
||||
const sessionId = `WFS-review-${Date.now()}`;
|
||||
Write(`.workflow/active/${sessionId}/workflow-session.json`, JSON.stringify({
|
||||
session_id: sessionId,
|
||||
type: "review",
|
||||
description: `Code review for ${targetPattern}`,
|
||||
created_at: new Date().toISOString()
|
||||
}, null, 2));
|
||||
```
|
||||
|
||||
### Step 1.2: Path Resolution & Validation
|
||||
|
||||
```bash
|
||||
# Expand glob pattern to file list (relative paths from project root)
|
||||
find . -path "./src/auth/**" -type f | sed 's|^\./||'
|
||||
|
||||
# Validate files exist and are readable
|
||||
for file in ${resolvedFiles[@]}; do
|
||||
test -r "$file" || error "File not readable: $file"
|
||||
done
|
||||
```
|
||||
|
||||
- Parse and expand file patterns (glob support): `src/auth/**` -> actual file list
|
||||
- Validation: Ensure all specified files exist and are readable
|
||||
- Store as **relative paths** from project root (e.g., `src/auth/service.ts`)
|
||||
- Agents construct absolute paths dynamically during execution
|
||||
|
||||
**Syntax Rules**:
|
||||
- All paths are **relative** from project root (e.g., `src/auth/**` not `/src/auth/**`)
|
||||
- Multiple patterns: comma-separated, **no spaces** (e.g., `src/auth/**,src/payment/**`)
|
||||
- Glob and specific files can be mixed (e.g., `src/auth/**,src/config.ts`)
|
||||
|
||||
**Supported Patterns**:
|
||||
| Pattern Type | Example | Description |
|
||||
|--------------|---------|-------------|
|
||||
| Glob directory | `src/auth/**` | All files under src/auth/ |
|
||||
| Glob with extension | `src/**/*.ts` | All .ts files under src/ |
|
||||
| Specific file | `src/payment/processor.ts` | Single file |
|
||||
| Multiple patterns | `src/auth/**,src/payment/**` | Comma-separated (no spaces) |
|
||||
|
||||
**Resolution Process**:
|
||||
1. Parse input pattern (split by comma, trim whitespace)
|
||||
2. Expand glob patterns to file list via `find` command
|
||||
3. Validate all files exist and are readable
|
||||
4. Error if pattern matches 0 files
|
||||
5. Store resolved file list in review-state.json
|
||||
|
||||
---
|
||||
|
||||
## Common Steps (Both Modes)
|
||||
|
||||
### Step 1.4: Output Directory Setup
|
||||
|
||||
- Output directory: `.workflow/active/${sessionId}/.review/`
|
||||
- Create directory structure:
|
||||
```bash
|
||||
mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
|
||||
```
|
||||
|
||||
### Step 1.5: Initialize Review State
|
||||
|
||||
- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations (merged metadata + state)
|
||||
- Session mode includes `git_changes` in metadata
|
||||
- Module mode includes `target_pattern` and `resolved_files` in metadata
|
||||
- Progress tracking: Create `review-progress.json` for progress tracking
|
||||
|
||||
### Step 1.6: Initialize Review Progress
|
||||
|
||||
- Create `review-progress.json` for real-time dashboard updates via polling
|
||||
- See [Review Progress JSON](#review-progress-json) schema below
|
||||
|
||||
### Step 1.7: Progress Tracking Initialization
|
||||
|
||||
- Set up progress tracking with hierarchical structure
|
||||
- Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
## Review State JSON (Session Mode)
|
||||
|
||||
**Purpose**: Unified state machine and metadata (merged from metadata + state)
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-payment-integration",
|
||||
"review_id": "review-20250125-143022",
|
||||
"review_type": "session",
|
||||
"metadata": {
|
||||
"created_at": "2025-01-25T14:30:22Z",
|
||||
"git_changes": {
|
||||
"commit_range": "abc123..def456",
|
||||
"files_changed": 15,
|
||||
"insertions": 342,
|
||||
"deletions": 128
|
||||
},
|
||||
"dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"max_iterations": 3
|
||||
},
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"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": [
|
||||
{
|
||||
"file": "src/payment/processor.ts",
|
||||
"finding_count": 5,
|
||||
"dimensions": ["security", "architecture", "quality"]
|
||||
}
|
||||
],
|
||||
"iterations": [
|
||||
{
|
||||
"iteration": 1,
|
||||
"findings_analyzed": ["uuid-1", "uuid-2"],
|
||||
"findings_resolved": 1,
|
||||
"findings_escalated": 1,
|
||||
"severity_change": {
|
||||
"before": {"critical": 2, "high": 5, "medium": 12, "low": 8},
|
||||
"after": {"critical": 1, "high": 6, "medium": 12, "low": 8}
|
||||
},
|
||||
"timestamp": "2025-01-25T14:30:00Z"
|
||||
}
|
||||
],
|
||||
"completion_criteria": {
|
||||
"target": "no_critical_findings_and_high_under_5",
|
||||
"current_status": "in_progress",
|
||||
"estimated_completion": "2 iterations remaining"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Field Descriptions**:
|
||||
- `phase`: Current execution phase (state machine pointer)
|
||||
- `current_iteration`: Iteration counter (used for max check)
|
||||
- `next_action`: Next step orchestrator should execute
|
||||
- `severity_distribution`: Aggregated counts across all dimensions
|
||||
- `critical_files`: Files appearing in 3+ dimensions with metadata
|
||||
- `iterations[]`: Historical log for trend analysis
|
||||
|
||||
## Review State JSON (Module Mode)
|
||||
|
||||
**Purpose**: Unified state machine and metadata (merged from metadata + state)
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"review_type": "module",
|
||||
"session_id": "WFS-auth-system",
|
||||
"metadata": {
|
||||
"created_at": "2025-01-25T14:30:22Z",
|
||||
"target_pattern": "src/auth/**",
|
||||
"resolved_files": [
|
||||
"src/auth/service.ts",
|
||||
"src/auth/validator.ts",
|
||||
"src/auth/middleware.ts"
|
||||
],
|
||||
"dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"max_iterations": 3
|
||||
},
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── review-state.json # Orchestrator state machine (includes metadata)
|
||||
├── 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
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Session Context
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .task/
|
||||
├── .summaries/
|
||||
└── .review/ # Review results (this command)
|
||||
└── (structure above)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
- **Variables**: `sessionId`, `reviewId`, `resolvedFiles`, `reviewMode`, `outputDir`
|
||||
- **Files**: `review-state.json`, `review-progress.json`
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 2: Parallel Review](02-parallel-review.md).
|
||||
549
.codex/skills/review-cycle/phases/02-parallel-review.md
Normal file
549
.codex/skills/review-cycle/phases/02-parallel-review.md
Normal file
@@ -0,0 +1,549 @@
|
||||
# Phase 2: Parallel Review Coordination
|
||||
|
||||
> Source: Shared from `commands/workflow/review-session-cycle.md` + `commands/workflow/review-module-cycle.md` Phase 2
|
||||
|
||||
## Overview
|
||||
|
||||
Launch 7 dimension-specific review agents simultaneously using cli-explore-agent in Deep Scan mode.
|
||||
|
||||
## 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']
|
||||
};
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Orchestrator Responsibilities
|
||||
|
||||
- Spawn 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
|
||||
- Progress tracking: Mark dimensions as completed
|
||||
- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout)
|
||||
- Lifecycle: spawn_agent → batch wait → close_agent for all 7 agents
|
||||
|
||||
## Agent Output Schemas
|
||||
|
||||
**Agent-produced JSON files follow standardized schemas**:
|
||||
|
||||
1. **Dimension Results** (cli-explore-agent output from parallel reviews)
|
||||
- Schema: `~/.codex/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: `~/.codex/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
|
||||
|
||||
## Review Agent Invocation Template
|
||||
|
||||
### Module Mode
|
||||
|
||||
**Review Agent** (parallel execution, 7 instances):
|
||||
|
||||
```javascript
|
||||
// Step 1: Spawn 7 agents in parallel
|
||||
const reviewAgents = [];
|
||||
const dimensions = ['security', 'architecture', 'quality', 'action-items', 'performance', 'maintainability', 'best-practices'];
|
||||
|
||||
dimensions.forEach(dimension => {
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
|
||||
2. Read review state: ${reviewStateJsonPath}
|
||||
3. Get target files: Read resolved_files from review-state.json
|
||||
4. Validate file access: bash(ls -la ${targetFiles.join(' ')})
|
||||
5. Execute: cat ~/.codex/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
## 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)
|
||||
- Custom Focus: ${customFocus || 'Standard dimension analysis'}
|
||||
- Mode: analysis (READ-ONLY)
|
||||
- Context Pattern: ${targetFiles.map(f => '@' + f).join(' ')}
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
|
||||
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at)
|
||||
- cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms
|
||||
- summary (FLAT structure), findings, cross_references
|
||||
|
||||
Summary MUST be FLAT (NOT nested by_severity):
|
||||
\`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\`
|
||||
|
||||
Finding required fields:
|
||||
- id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase)
|
||||
- severity: lowercase only (critical|high|medium|low)
|
||||
- snippet (NOT code_snippet), impact (NOT exploit_scenario)
|
||||
- metadata, iteration (0), status (pending_remediation), cross_references
|
||||
|
||||
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
|
||||
- [ ] Schema obtained via cat review-dimension-results-schema.json
|
||||
- [ ] 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 follows schema exactly
|
||||
- [ ] Report is comprehensive and well-organized
|
||||
`
|
||||
});
|
||||
|
||||
reviewAgents.push(agentId);
|
||||
});
|
||||
|
||||
// Step 2: Batch wait for all 7 agents
|
||||
const reviewResults = wait({
|
||||
ids: reviewAgents,
|
||||
timeout_ms: 3600000 // 60 minutes
|
||||
});
|
||||
|
||||
// Step 3: Check results and handle timeouts
|
||||
if (reviewResults.timed_out) {
|
||||
console.log('Some dimension reviews timed out, continuing with completed results');
|
||||
}
|
||||
|
||||
reviewAgents.forEach((agentId, index) => {
|
||||
const dimension = dimensions[index];
|
||||
if (reviewResults.status[agentId].completed) {
|
||||
console.log(`${dimension} review completed`);
|
||||
} else {
|
||||
console.log(`${dimension} review failed or timed out`);
|
||||
}
|
||||
});
|
||||
|
||||
// Step 4: Cleanup all agents
|
||||
reviewAgents.forEach(id => close_agent({ id }));
|
||||
```
|
||||
|
||||
### Session Mode
|
||||
|
||||
**Review Agent** (parallel execution, 7 instances):
|
||||
|
||||
```javascript
|
||||
// Step 1: Spawn 7 agents in parallel
|
||||
const reviewAgents = [];
|
||||
const dimensions = ['security', 'architecture', 'quality', 'action-items', 'performance', 'maintainability', 'best-practices'];
|
||||
|
||||
dimensions.forEach(dimension => {
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
|
||||
2. Read session metadata: ${sessionMetadataPath}
|
||||
3. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f)
|
||||
4. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
|
||||
5. Read review state: ${reviewStateJsonPath}
|
||||
6. Execute: cat ~/.codex/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
|
||||
7. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
8. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
|
||||
|
||||
---
|
||||
|
||||
## Task Objective
|
||||
Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for completed implementation in session ${sessionId}
|
||||
|
||||
## 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)
|
||||
|
||||
## Session Context
|
||||
- Session ID: ${sessionId}
|
||||
- Review Dimension: ${dimension}
|
||||
- Review ID: ${reviewId}
|
||||
- Implementation Phase: Complete (all tests passing)
|
||||
- Output Directory: ${outputDir}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex (fallback chain)
|
||||
- Template: ~/.codex/workflows/cli-templates/prompts/analysis/${dimensionTemplate}
|
||||
- Custom Focus: ${customFocus || 'Standard dimension analysis'}
|
||||
- Timeout: ${timeout}ms
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
|
||||
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at)
|
||||
- cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms
|
||||
- summary (FLAT structure), findings, cross_references
|
||||
|
||||
Summary MUST be FLAT (NOT nested by_severity):
|
||||
\`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\`
|
||||
|
||||
Finding required fields:
|
||||
- id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase)
|
||||
- severity: lowercase only (critical|high|medium|low)
|
||||
- snippet (NOT code_snippet), impact (NOT exploit_scenario)
|
||||
- metadata, iteration (0), status (pending_remediation), cross_references
|
||||
|
||||
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
|
||||
- [ ] Schema obtained via cat review-dimension-results-schema.json
|
||||
- [ ] All changed 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 follows schema exactly
|
||||
- [ ] Report is comprehensive and well-organized
|
||||
`
|
||||
});
|
||||
|
||||
reviewAgents.push(agentId);
|
||||
});
|
||||
|
||||
// Step 2: Batch wait for all 7 agents
|
||||
const reviewResults = wait({
|
||||
ids: reviewAgents,
|
||||
timeout_ms: 3600000 // 60 minutes
|
||||
});
|
||||
|
||||
// Step 3: Check results and handle timeouts
|
||||
if (reviewResults.timed_out) {
|
||||
console.log('Some dimension reviews timed out, continuing with completed results');
|
||||
}
|
||||
|
||||
reviewAgents.forEach((agentId, index) => {
|
||||
const dimension = dimensions[index];
|
||||
if (reviewResults.status[agentId].completed) {
|
||||
console.log(`${dimension} review completed`);
|
||||
} else {
|
||||
console.log(`${dimension} review failed or timed out`);
|
||||
}
|
||||
});
|
||||
|
||||
// Step 4: Cleanup all agents
|
||||
reviewAgents.forEach(id => close_agent({ id }));
|
||||
```
|
||||
|
||||
## Deep-Dive Agent Invocation Template
|
||||
|
||||
**Deep-Dive Agent** (iteration execution):
|
||||
|
||||
```javascript
|
||||
// Spawn deep-dive agent
|
||||
const deepDiveAgentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
|
||||
2. Read original finding: ${dimensionJsonPath}
|
||||
3. Read affected file: ${file}
|
||||
4. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
|
||||
5. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
|
||||
6. Execute: cat ~/.codex/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
7. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
8. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
---
|
||||
|
||||
## 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}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
- Template: ~/.codex/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
|
||||
|
||||
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- finding_id, dimension, iteration, analysis_timestamp
|
||||
- cli_tool_used, model, analysis_duration_ms
|
||||
- original_finding, root_cause, remediation_plan
|
||||
- impact_assessment, reassessed_severity, confidence_score, cross_references
|
||||
|
||||
All nested objects must follow schema exactly - read schema for field names
|
||||
|
||||
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
|
||||
- [ ] Schema obtained via cat review-deep-dive-results-schema.json
|
||||
- [ ] 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
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] References include project-specific and external documentation
|
||||
`
|
||||
});
|
||||
|
||||
// Wait for completion
|
||||
const deepDiveResult = wait({
|
||||
ids: [deepDiveAgentId],
|
||||
timeout_ms: 2400000 // 40 minutes
|
||||
});
|
||||
|
||||
// Cleanup
|
||||
close_agent({ id: deepDiveAgentId });
|
||||
```
|
||||
|
||||
## 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^2) 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^2) 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';
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- Files: `dimensions/{dimension}.json`, `reports/{dimension}-analysis.md`, `reports/{dimension}-cli-output.txt`
|
||||
- Progress: Mark Phase 2 completed, Phase 3 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 3: Aggregation](03-aggregation.md).
|
||||
74
.codex/skills/review-cycle/phases/03-aggregation.md
Normal file
74
.codex/skills/review-cycle/phases/03-aggregation.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Phase 3: Aggregation
|
||||
|
||||
> Source: Shared from `commands/workflow/review-session-cycle.md` + `commands/workflow/review-module-cycle.md` Phase 3
|
||||
|
||||
## Overview
|
||||
|
||||
Load all dimension results, calculate severity distribution, identify cross-cutting concerns, and decide whether to enter iterative deep-dive (Phase 4) or proceed to completion (Phase 5).
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 3.1: Load Dimension Results
|
||||
|
||||
- Load all dimension JSON files from `{outputDir}/dimensions/`
|
||||
- Parse each file following review-dimension-results-schema.json
|
||||
- Handle missing files gracefully (log warning, skip)
|
||||
|
||||
### Step 3.2: Calculate Severity Distribution
|
||||
|
||||
- Count findings by severity level: critical, high, medium, low
|
||||
- Store in review-state.json `severity_distribution` field
|
||||
|
||||
### Step 3.3: Cross-Cutting Concern Detection
|
||||
|
||||
**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**
|
||||
|
||||
### Step 3.4: Deep-Dive Selection
|
||||
|
||||
**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)
|
||||
|
||||
### Step 3.5: Decision Logic
|
||||
|
||||
**Iteration Trigger**:
|
||||
- Critical findings > 0 OR
|
||||
- High findings > 5 OR
|
||||
- Critical files count > 0
|
||||
|
||||
If any trigger condition is met, proceed to Phase 4 (Iterative Deep-Dive). Otherwise, skip to Phase 5 (Completion).
|
||||
|
||||
### Step 3.6: Update State
|
||||
|
||||
- Update review-state.json with aggregation results
|
||||
- Update review-progress.json
|
||||
|
||||
**Phase 3 Orchestrator Responsibilities**:
|
||||
- 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
|
||||
|
||||
## Severity Assessment Reference
|
||||
|
||||
**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
|
||||
|
||||
## Output
|
||||
|
||||
- Variables: severityDistribution, criticalFiles, deepDiveFindings, shouldIterate (boolean)
|
||||
- State: review-state.json updated with aggregation results
|
||||
|
||||
## Next Phase
|
||||
|
||||
- If shouldIterate: [Phase 4: Iterative Deep-Dive](04-iterative-deep-dive.md)
|
||||
- Else: [Phase 5: Review Completion](05-review-completion.md)
|
||||
333
.codex/skills/review-cycle/phases/04-iterative-deep-dive.md
Normal file
333
.codex/skills/review-cycle/phases/04-iterative-deep-dive.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# Phase 4: Iterative Deep-Dive
|
||||
|
||||
> Source: Shared from `commands/workflow/review-session-cycle.md` + `commands/workflow/review-module-cycle.md` Phase 4
|
||||
|
||||
## Overview
|
||||
|
||||
Perform focused root cause analysis on critical findings. Select up to 5 findings per iteration, launch deep-dive agents, re-assess severity, and loop back to aggregation if needed.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Phase 3 determined shouldIterate = true
|
||||
- Available: severityDistribution, criticalFiles, deepDiveFindings
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 4.1: Check Iteration Limit
|
||||
|
||||
- Check `current_iteration` < `max_iterations` (default 3)
|
||||
- If exceeded: Log iteration limit reached, skip to Phase 5
|
||||
- Default iterations: 1 (deep-dive runs once; use --max-iterations=0 to skip entirely)
|
||||
|
||||
### Step 4.2: Select Findings for Deep-Dive
|
||||
|
||||
**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)
|
||||
|
||||
**Selection algorithm**:
|
||||
1. Collect all findings with severity = critical -> add to selection
|
||||
2. If selection < 5: add high-severity findings from critical files (files in 3+ dimensions), sorted by dimension count descending
|
||||
3. Cap at 5 total findings
|
||||
|
||||
### Step 4.3: Launch Deep-Dive Agents
|
||||
|
||||
- Spawn cli-explore-agent for each selected finding
|
||||
- Use Dependency Map + Deep Scan mode
|
||||
- Each agent runs independently (can be launched in parallel)
|
||||
- Tool priority: gemini -> qwen -> codex (fallback on error/timeout)
|
||||
- Lifecycle: spawn_agent → batch wait → close_agent
|
||||
|
||||
### Step 4.4: Collect Results
|
||||
|
||||
- Parse iteration JSON files from `{outputDir}/iterations/iteration-{N}-finding-{uuid}.json`
|
||||
- Extract reassessed severities from each result
|
||||
- Collect remediation plans and impact assessments
|
||||
- Handle agent failures gracefully (log warning, mark finding as unanalyzed)
|
||||
|
||||
### Step 4.5: Re-Aggregate
|
||||
|
||||
- Update severity distribution based on reassessments
|
||||
- Record iteration in review-state.json `iterations[]` array:
|
||||
|
||||
```json
|
||||
{
|
||||
"iteration": 1,
|
||||
"findings_analyzed": ["uuid-1", "uuid-2"],
|
||||
"findings_resolved": 1,
|
||||
"findings_escalated": 1,
|
||||
"severity_change": {
|
||||
"before": {"critical": 2, "high": 5, "medium": 12, "low": 8},
|
||||
"after": {"critical": 1, "high": 6, "medium": 12, "low": 8}
|
||||
},
|
||||
"timestamp": "2025-01-25T14:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
- Increment `current_iteration` in review-state.json
|
||||
- Re-evaluate decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist
|
||||
- Loop back to Phase 3 aggregation check if conditions still met
|
||||
|
||||
## Deep-Dive Agent Invocation Template
|
||||
|
||||
### Module Mode
|
||||
|
||||
```javascript
|
||||
// Step 1: Spawn deep-dive agents in parallel
|
||||
const deepDiveAgents = [];
|
||||
|
||||
selectedFindings.forEach(finding => {
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
|
||||
2. Read original finding: ${dimensionJsonPath}
|
||||
3. Read affected file: ${finding.file}
|
||||
4. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${projectDir}/src --include="*.ts")
|
||||
5. Read test files: bash(find ${projectDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
|
||||
6. Execute: cat ~/.codex/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
7. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
8. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
---
|
||||
|
||||
## 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 ${finding.dimension} issue
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Dependency Map mode** first to understand dependencies:
|
||||
- Build dependency graph around ${finding.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: ${finding.id}
|
||||
- Original Dimension: ${finding.dimension}
|
||||
- Title: ${finding.title}
|
||||
- File: ${finding.file}:${finding.line}
|
||||
- Severity: ${finding.severity}
|
||||
- Category: ${finding.category}
|
||||
- Original Description: ${finding.description}
|
||||
- Iteration: ${iteration}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
- Template: ~/.codex/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
|
||||
|
||||
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${finding.id}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- finding_id, dimension, iteration, analysis_timestamp
|
||||
- cli_tool_used, model, analysis_duration_ms
|
||||
- original_finding, root_cause, remediation_plan
|
||||
- impact_assessment, reassessed_severity, confidence_score, cross_references
|
||||
|
||||
All nested objects must follow schema exactly - read schema for field names
|
||||
|
||||
2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${finding.id}.md
|
||||
- Detailed root cause analysis
|
||||
- Step-by-step remediation plan
|
||||
- Impact assessment and rollback strategy
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat review-deep-dive-results-schema.json
|
||||
- [ ] 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
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] References include project-specific and external documentation
|
||||
`
|
||||
});
|
||||
|
||||
deepDiveAgents.push(agentId);
|
||||
});
|
||||
|
||||
// Step 2: Batch wait for all deep-dive agents
|
||||
const deepDiveResults = wait({
|
||||
ids: deepDiveAgents,
|
||||
timeout_ms: 2400000 // 40 minutes
|
||||
});
|
||||
|
||||
// Step 3: Collect results
|
||||
deepDiveAgents.forEach((agentId, index) => {
|
||||
const finding = selectedFindings[index];
|
||||
if (deepDiveResults.status[agentId].completed) {
|
||||
console.log(`Deep-dive completed for ${finding.id}`);
|
||||
} else {
|
||||
console.log(`Deep-dive failed/timed out for ${finding.id}`);
|
||||
}
|
||||
});
|
||||
|
||||
// Step 4: Cleanup all agents
|
||||
deepDiveAgents.forEach(id => close_agent({ id }));
|
||||
```
|
||||
|
||||
### Session Mode
|
||||
|
||||
```javascript
|
||||
// Step 1: Spawn deep-dive agents in parallel
|
||||
const deepDiveAgents = [];
|
||||
|
||||
selectedFindings.forEach(finding => {
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
|
||||
2. Read original finding: ${dimensionJsonPath}
|
||||
3. Read affected file: ${finding.file}
|
||||
4. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${workflowDir}/src --include="*.ts")
|
||||
5. Read test files: bash(find ${workflowDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
|
||||
6. Execute: cat ~/.codex/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
7. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
8. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
---
|
||||
|
||||
## 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 ${finding.dimension} issue
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Dependency Map mode** first to understand dependencies:
|
||||
- Build dependency graph around ${finding.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: ${finding.id}
|
||||
- Original Dimension: ${finding.dimension}
|
||||
- Title: ${finding.title}
|
||||
- File: ${finding.file}:${finding.line}
|
||||
- Severity: ${finding.severity}
|
||||
- Category: ${finding.category}
|
||||
- Original Description: ${finding.description}
|
||||
- Iteration: ${iteration}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
- Template: ~/.codex/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
|
||||
- Timeout: 2400000ms (40 minutes)
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
|
||||
|
||||
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${finding.id}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- finding_id, dimension, iteration, analysis_timestamp
|
||||
- cli_tool_used, model, analysis_duration_ms
|
||||
- original_finding, root_cause, remediation_plan
|
||||
- impact_assessment, reassessed_severity, confidence_score, cross_references
|
||||
|
||||
All nested objects must follow schema exactly - read schema for field names
|
||||
|
||||
2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${finding.id}.md
|
||||
- Detailed root cause analysis
|
||||
- Step-by-step remediation plan
|
||||
- Impact assessment and rollback strategy
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat review-deep-dive-results-schema.json
|
||||
- [ ] 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
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] References include project-specific and external documentation
|
||||
`
|
||||
});
|
||||
|
||||
deepDiveAgents.push(agentId);
|
||||
});
|
||||
|
||||
// Step 2: Batch wait for all deep-dive agents
|
||||
const deepDiveResults = wait({
|
||||
ids: deepDiveAgents,
|
||||
timeout_ms: 2400000 // 40 minutes
|
||||
});
|
||||
|
||||
// Step 3: Collect results
|
||||
deepDiveAgents.forEach((agentId, index) => {
|
||||
const finding = selectedFindings[index];
|
||||
if (deepDiveResults.status[agentId].completed) {
|
||||
console.log(`Deep-dive completed for ${finding.id}`);
|
||||
} else {
|
||||
console.log(`Deep-dive failed/timed out for ${finding.id}`);
|
||||
}
|
||||
});
|
||||
|
||||
// Step 4: Cleanup all agents
|
||||
deepDiveAgents.forEach(id => close_agent({ id }));
|
||||
```
|
||||
|
||||
## Key Differences Between Modes
|
||||
|
||||
| Aspect | Module Mode | Session Mode |
|
||||
|--------|-------------|--------------|
|
||||
| MANDATORY STEP 4 | `${projectDir}/src` | `${workflowDir}/src` |
|
||||
| MANDATORY STEP 5 | `${projectDir}/tests` | `${workflowDir}/tests` |
|
||||
| CLI Timeout | (not specified) | 2400000ms (40 minutes) |
|
||||
|
||||
## Iteration Control
|
||||
|
||||
**Phase 4 Orchestrator Responsibilities**:
|
||||
- Check iteration count < max_iterations (default 3)
|
||||
- Spawn 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
|
||||
|
||||
**Termination Conditions** (any one stops iteration):
|
||||
1. `current_iteration` >= `max_iterations`
|
||||
2. No critical findings remaining AND high findings <= 5 AND no critical files
|
||||
3. No findings selected for deep-dive (all resolved or downgraded)
|
||||
|
||||
**State Updates Per Iteration**:
|
||||
- `review-state.json`: Increment `current_iteration`, append to `iterations[]`, update `severity_distribution`, set `next_action`
|
||||
- `review-progress.json`: Update `deep_dive.analyzed` count, `deep_dive.percent_complete`, `phase`
|
||||
|
||||
## Output
|
||||
|
||||
- Files: `iterations/iteration-{N}-finding-{uuid}.json`, `reports/deep-dive-{N}-{uuid}.md`
|
||||
- State: review-state.json `iterations[]` updated
|
||||
- Decision: Re-enter Phase 3 aggregation or proceed to Phase 5
|
||||
|
||||
## Next Phase
|
||||
|
||||
- If still has critical findings AND iterations < max: Loop to [Phase 3: Aggregation](03-aggregation.md)
|
||||
- Else: [Phase 5: Review Completion](05-review-completion.md)
|
||||
173
.codex/skills/review-cycle/phases/05-review-completion.md
Normal file
173
.codex/skills/review-cycle/phases/05-review-completion.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# Phase 5: Review Completion
|
||||
|
||||
> Source: Shared from `commands/workflow/review-session-cycle.md` + `commands/workflow/review-module-cycle.md` Phase 5
|
||||
|
||||
## Overview
|
||||
|
||||
Finalize review state, generate completion statistics, and optionally prompt for automated fix pipeline.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 5.1: Finalize State
|
||||
|
||||
**Phase 5 Orchestrator Responsibilities**:
|
||||
- Finalize review-progress.json with completion statistics
|
||||
- Update review-state.json with completion_time and phase=complete
|
||||
- Progress tracking: Mark all tasks done
|
||||
|
||||
**review-state.json updates**:
|
||||
```json
|
||||
{
|
||||
"phase": "complete",
|
||||
"completion_time": "2025-01-25T15:00:00Z",
|
||||
"next_action": "none"
|
||||
}
|
||||
```
|
||||
|
||||
**review-progress.json updates**:
|
||||
```json
|
||||
{
|
||||
"phase": "complete",
|
||||
"overall_percent": 100,
|
||||
"completion_time": "2025-01-25T15:00:00Z",
|
||||
"final_severity_distribution": {
|
||||
"critical": 0,
|
||||
"high": 3,
|
||||
"medium": 12,
|
||||
"low": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5.2: Evaluate Completion Status
|
||||
|
||||
**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
|
||||
|
||||
### Step 5.3: Progress Tracking Completion
|
||||
|
||||
Update progress tracking to reflect all phases completed:
|
||||
```
|
||||
Phase 1: Discovery & Initialization → completed
|
||||
Phase 2: Parallel Reviews (7 dimensions) → completed
|
||||
→ Security review → completed
|
||||
→ Architecture review → completed
|
||||
→ Quality review → completed
|
||||
... other dimensions as sub-items
|
||||
Phase 3: Aggregation → completed
|
||||
Phase 4: Deep-dive → completed
|
||||
Phase 5: Completion → completed
|
||||
```
|
||||
|
||||
### Step 5.4: Fix Pipeline Prompt
|
||||
|
||||
- Ask user: "Run automated fixes on findings? [Y/n]"
|
||||
- If confirmed AND --fix flag: Continue to Phase 6
|
||||
- Display summary of findings by severity:
|
||||
|
||||
```
|
||||
Review Complete - Summary:
|
||||
Critical: 0 High: 3 Medium: 12 Low: 8
|
||||
Total findings: 23
|
||||
Dimensions reviewed: 7/7
|
||||
Iterations completed: 2/3
|
||||
|
||||
Run automated fixes on findings? [Y/n]
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Error Handling Reference
|
||||
|
||||
### Phase-Level Error Matrix
|
||||
|
||||
| Phase | Error | Blocking? | Action |
|
||||
|-------|-------|-----------|--------|
|
||||
| Phase 1 | Invalid path pattern / Session not found | Yes | Error and exit |
|
||||
| Phase 1 | No files matched / No completed tasks | Yes | Error and exit |
|
||||
| Phase 1 | Files not readable / No changed files | Yes | Error and exit |
|
||||
| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
|
||||
| Phase 2 | All dimensions fail | Yes | Error and exit |
|
||||
| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
|
||||
| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
|
||||
| Phase 4 | Max iterations reached | No | Generate partial report |
|
||||
|
||||
### CLI Fallback Chain
|
||||
|
||||
Gemini -> Qwen -> Codex -> degraded mode
|
||||
|
||||
### Fallback Triggers
|
||||
|
||||
1. HTTP 429, 5xx errors, connection timeout
|
||||
2. Invalid JSON output (parse error, missing required fields)
|
||||
3. Low confidence score < 0.4
|
||||
4. Analysis too brief (< 100 words in report)
|
||||
|
||||
### Fallback Behavior
|
||||
|
||||
- On trigger: Retry with next tool in chain
|
||||
- After Codex fails: Enter degraded mode (skip analysis, log error)
|
||||
- Degraded mode: Continue workflow with available results
|
||||
|
||||
## 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
|
||||
|
||||
## Related Commands
|
||||
|
||||
### View Review Progress
|
||||
|
||||
Use `ccw view` to open the review dashboard in browser:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
|
||||
### Automated Fix Workflow
|
||||
|
||||
After completing a review, use the generated findings JSON for automated fixing:
|
||||
|
||||
```bash
|
||||
# Step 1: Complete review (this skill)
|
||||
review-cycle src/auth/**
|
||||
# OR
|
||||
review-cycle
|
||||
|
||||
# Step 2: Run automated fixes using dimension findings
|
||||
review-cycle --fix .workflow/active/WFS-{session-id}/.review/
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- State: review-state.json (phase=complete), review-progress.json (final)
|
||||
- Decision: fix pipeline or end
|
||||
|
||||
## Next Phase
|
||||
|
||||
- If fix requested: [Phase 6: Fix Discovery & Batching](06-fix-discovery-batching.md)
|
||||
- Else: Workflow complete
|
||||
238
.codex/skills/review-cycle/phases/06-fix-discovery-batching.md
Normal file
238
.codex/skills/review-cycle/phases/06-fix-discovery-batching.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Phase 6: Fix Discovery & Batching
|
||||
|
||||
> Source: `commands/workflow/review-cycle-fix.md` Phase 1 + Phase 1.5
|
||||
|
||||
## Overview
|
||||
|
||||
Validate fix input source, create fix session structure, and perform intelligent grouping of findings into batches for parallel planning.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Fix from exported findings file (session-based path)
|
||||
review-cycle --fix .workflow/active/WFS-123/.review/fix-export-1706184622000.json
|
||||
|
||||
# Fix from review directory (auto-discovers latest export)
|
||||
review-cycle --fix .workflow/active/WFS-123/.review/
|
||||
|
||||
# Resume interrupted fix session
|
||||
review-cycle --fix --resume
|
||||
|
||||
# Custom max retry attempts per finding
|
||||
review-cycle --fix .workflow/active/WFS-123/.review/ --max-iterations=5
|
||||
|
||||
# Custom batch size for parallel planning (default: 5 findings per batch)
|
||||
review-cycle --fix .workflow/active/WFS-123/.review/ --batch-size=3
|
||||
```
|
||||
|
||||
**Fix Source**: Exported findings from review cycle dashboard
|
||||
**Output Directory**: `{review-dir}/fixes/{fix-session-id}/` (within session .review/)
|
||||
**Default Max Iterations**: 3 (per finding, adjustable)
|
||||
**Default Batch Size**: 5 (findings per planning batch, adjustable)
|
||||
**Max Parallel Agents**: 10 (concurrent planning agents)
|
||||
**CLI Tools**: @cli-planning-agent (planning), @cli-execute-agent (fixing)
|
||||
|
||||
## Core Concept
|
||||
|
||||
Automated fix orchestrator with **parallel planning architecture**: Multiple AI agents analyze findings concurrently in batches, then coordinate parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, executes fixes with conservative test verification.
|
||||
|
||||
**Fix Process**:
|
||||
- **Batching Phase (1.5)**: Orchestrator groups findings by file+dimension similarity, creates batches
|
||||
- **Planning Phase (2)**: Up to 10 agents plan batches in parallel, generate partial plans, orchestrator aggregates
|
||||
- **Execution Phase (3)**: Main orchestrator coordinates agents per aggregated timeline stages
|
||||
- **Parallel Efficiency**: Customizable batch size (default: 5), MAX_PARALLEL=10 agents
|
||||
- **No rigid structure**: Adapts to task requirements, not bound to fixed JSON format
|
||||
|
||||
**vs Manual Fixing**:
|
||||
- **Manual**: Developer reviews findings one-by-one, fixes sequentially
|
||||
- **Automated**: AI groups related issues, multiple agents plan in parallel, executes in optimal parallel/serial order with automatic test verification
|
||||
|
||||
### Value Proposition
|
||||
1. **Parallel Planning**: Multiple agents analyze findings concurrently, reducing planning time for large batches (10+ findings)
|
||||
2. **Intelligent Batching**: Semantic similarity grouping ensures related findings are analyzed together
|
||||
3. **Multi-stage Coordination**: Supports complex parallel + serial execution with cross-batch dependency management
|
||||
4. **Conservative Safety**: Mandatory test verification with automatic rollback on failure
|
||||
5. **Resume Support**: Checkpoint-based recovery for interrupted sessions
|
||||
|
||||
### Orchestrator Boundary (CRITICAL)
|
||||
- **ONLY command** for automated review finding fixes
|
||||
- Manages: Intelligent batching (Phase 1.5), parallel planning coordination (spawn N agents), plan aggregation (merge partial plans, resolve cross-batch dependencies), stage-based execution scheduling, agent scheduling, progress tracking
|
||||
- Delegates: Batch planning to @cli-planning-agent, fix execution to @cli-execute-agent
|
||||
|
||||
## Fix Process Overview
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization
|
||||
└─ Validate export file, create fix session structure, initialize state files
|
||||
|
||||
Phase 1.5: Intelligent Grouping & Batching
|
||||
├─ Analyze findings metadata (file, dimension, severity)
|
||||
├─ Group by semantic similarity (file proximity + dimension affinity)
|
||||
├─ Create batches respecting --batch-size (default: 5)
|
||||
└─ Output: Finding batches for parallel planning
|
||||
|
||||
Phase 2: Parallel Planning Coordination (@cli-planning-agent × N)
|
||||
├─ Spawn MAX_PARALLEL planning agents concurrently (default: 10)
|
||||
├─ Each agent processes one batch:
|
||||
│ ├─ Analyze findings for patterns and dependencies
|
||||
│ ├─ Group by file + dimension + root cause similarity
|
||||
│ ├─ Determine execution strategy (parallel/serial/hybrid)
|
||||
│ ├─ Generate fix timeline with stages
|
||||
│ └─ Output: partial-plan-{batch-id}.json
|
||||
├─ Collect results from all agents
|
||||
└─ Aggregate: Merge partial plans → fix-plan.json (resolve cross-batch dependencies)
|
||||
|
||||
Phase 3: Execution Orchestration (Stage-based)
|
||||
For each timeline stage:
|
||||
├─ Load groups for this stage
|
||||
├─ If parallel: Spawn all group agents simultaneously
|
||||
├─ If serial: Execute groups sequentially
|
||||
├─ Each agent:
|
||||
│ ├─ Analyze code context
|
||||
│ ├─ Apply fix per strategy
|
||||
│ ├─ Run affected tests
|
||||
│ ├─ On test failure: Rollback, retry up to max_iterations
|
||||
│ └─ On success: Commit, update fix-progress-{N}.json
|
||||
└─ Advance to next stage
|
||||
|
||||
Phase 4: Completion & Aggregation
|
||||
└─ Aggregate results → Generate fix-summary.md → Update history → Output summary
|
||||
|
||||
Phase 5: Session Completion (Optional)
|
||||
└─ If all fixes successful → Prompt to complete workflow session
|
||||
```
|
||||
|
||||
## Agent Roles
|
||||
|
||||
| Agent | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Orchestrator** | Input validation, session management, intelligent batching (Phase 1.5), parallel planning coordination (spawn N agents), plan aggregation (merge partial plans, resolve cross-batch dependencies), stage-based execution scheduling, progress tracking, result aggregation |
|
||||
| **@cli-planning-agent** | Batch findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping, partial plan output |
|
||||
| **@cli-execute-agent** | Fix execution per group, code context analysis, Edit tool operations, test verification, git rollback on failure, completion JSON generation |
|
||||
|
||||
## Parallel Planning Architecture
|
||||
|
||||
**Batch Processing Strategy**:
|
||||
|
||||
| Phase | Agent Count | Input | Output | Purpose |
|
||||
|-------|-------------|-------|--------|---------|
|
||||
| **Batching (1.5)** | Orchestrator | All findings | Finding batches | Semantic grouping by file+dimension, respecting --batch-size |
|
||||
| **Planning (2)** | N agents (≤10) | 1 batch each | partial-plan-{batch-id}.json | Analyze batch in parallel, generate execution groups and timeline |
|
||||
| **Aggregation (2)** | Orchestrator | All partial plans | fix-plan.json | Merge timelines, resolve cross-batch dependencies |
|
||||
| **Execution (3)** | M agents (dynamic) | 1 group each | fix-progress-{N}.json | Execute fixes per aggregated plan with test verification |
|
||||
|
||||
**Benefits**:
|
||||
- **Speed**: N agents plan concurrently, reducing planning time for large batches
|
||||
- **Scalability**: MAX_PARALLEL=10 prevents resource exhaustion
|
||||
- **Flexibility**: Batch size customizable via --batch-size (default: 5)
|
||||
- **Isolation**: Each planning agent focuses on related findings (semantic grouping)
|
||||
- **Reusable**: Aggregated plan can be re-executed without re-planning
|
||||
|
||||
## Intelligent Grouping Strategy
|
||||
|
||||
**Three-Level Grouping**:
|
||||
|
||||
```javascript
|
||||
// Level 1: Primary grouping by file + dimension
|
||||
{file: "auth.ts", dimension: "security"} → Group A
|
||||
{file: "auth.ts", dimension: "quality"} → Group B
|
||||
{file: "query-builder.ts", dimension: "security"} → Group C
|
||||
|
||||
// Level 2: Secondary grouping by root cause similarity
|
||||
Group A findings → Semantic similarity analysis (threshold 0.7)
|
||||
→ Sub-group A1: "missing-input-validation" (findings 1, 2)
|
||||
→ Sub-group A2: "insecure-crypto" (finding 3)
|
||||
|
||||
// Level 3: Dependency analysis
|
||||
Sub-group A1 creates validation utilities
|
||||
Sub-group C4 depends on those utilities
|
||||
→ A1 must execute before C4 (serial stage dependency)
|
||||
```
|
||||
|
||||
**Similarity Computation**:
|
||||
- Combine: `description + recommendation + category`
|
||||
- Vectorize: TF-IDF or LLM embedding
|
||||
- Cluster: Greedy algorithm with cosine similarity > 0.7
|
||||
|
||||
## Phase 1: Discovery & Initialization (Orchestrator)
|
||||
|
||||
**Phase 1 Orchestrator Responsibilities**:
|
||||
- Input validation: Check export file exists and is valid JSON
|
||||
- Auto-discovery: If review-dir provided, find latest `*-fix-export.json`
|
||||
- Session creation: Generate fix-session-id (`fix-{timestamp}`)
|
||||
- Directory structure: Create `{review-dir}/fixes/{fix-session-id}/` with subdirectories
|
||||
- State files: Initialize active-fix-session.json (session marker)
|
||||
- Progress tracking initialization: Set up 5-phase tracking (including Phase 1.5)
|
||||
|
||||
## Phase 1.5: Intelligent Grouping & Batching (Orchestrator)
|
||||
|
||||
- Load all findings metadata (id, file, dimension, severity, title)
|
||||
- Semantic similarity analysis:
|
||||
- Primary: Group by file proximity (same file or related modules)
|
||||
- Secondary: Group by dimension affinity (same review dimension)
|
||||
- Tertiary: Analyze title/description similarity (root cause clustering)
|
||||
- Create batches respecting --batch-size (default: 5 findings per batch)
|
||||
- Balance workload: Distribute high-severity findings across batches
|
||||
- Output: Array of finding batches for parallel planning
|
||||
|
||||
```javascript
|
||||
// Load findings
|
||||
const findings = JSON.parse(Read(exportFile));
|
||||
const batchSize = flags.batchSize || 5;
|
||||
|
||||
// Semantic similarity analysis: group by file+dimension
|
||||
const batches = [];
|
||||
const grouped = new Map(); // key: "${file}:${dimension}"
|
||||
|
||||
for (const finding of findings) {
|
||||
const key = `${finding.file || 'unknown'}:${finding.dimension || 'general'}`;
|
||||
if (!grouped.has(key)) grouped.set(key, []);
|
||||
grouped.get(key).push(finding);
|
||||
}
|
||||
|
||||
// Create batches respecting batchSize
|
||||
for (const [key, group] of grouped) {
|
||||
while (group.length > 0) {
|
||||
const batch = group.splice(0, batchSize);
|
||||
batches.push({
|
||||
batch_id: batches.length + 1,
|
||||
findings: batch,
|
||||
metadata: { primary_file: batch[0].file, primary_dimension: batch[0].dimension }
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`Created ${batches.length} batches (${batchSize} findings per batch)`);
|
||||
```
|
||||
|
||||
## Output File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── fix-export-{timestamp}.json # Exported findings (input)
|
||||
└── fixes/{fix-session-id}/
|
||||
├── partial-plan-1.json # Batch 1 partial plan (planning agent 1 output)
|
||||
├── partial-plan-2.json # Batch 2 partial plan (planning agent 2 output)
|
||||
├── partial-plan-N.json # Batch N partial plan (planning agent N output)
|
||||
├── fix-plan.json # Aggregated execution plan (orchestrator merges partials)
|
||||
├── fix-progress-1.json # Group 1 progress (planning agent init → agent updates)
|
||||
├── fix-progress-2.json # Group 2 progress (planning agent init → agent updates)
|
||||
├── fix-progress-3.json # Group 3 progress (planning agent init → agent updates)
|
||||
├── fix-summary.md # Final report (orchestrator generates)
|
||||
├── active-fix-session.json # Active session marker
|
||||
└── fix-history.json # All sessions history
|
||||
```
|
||||
|
||||
**File Producers**:
|
||||
- **Orchestrator**: Batches findings (Phase 1.5), aggregates partial plans → `fix-plan.json` (Phase 2), spawns parallel planning agents
|
||||
- **Planning Agents (N)**: Each outputs `partial-plan-{batch-id}.json` + initializes `fix-progress-*.json` for assigned groups
|
||||
- **Execution Agents (M)**: Update assigned `fix-progress-{N}.json` in real-time
|
||||
|
||||
## Output
|
||||
|
||||
- Variables: batches (array), fixSessionId, sessionDir
|
||||
- Files: active-fix-session.json, directory structure created
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 7: Fix Parallel Planning](07-fix-parallel-planning.md).
|
||||
224
.codex/skills/review-cycle/phases/07-fix-parallel-planning.md
Normal file
224
.codex/skills/review-cycle/phases/07-fix-parallel-planning.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Phase 7: Fix Parallel Planning
|
||||
|
||||
> Source: `commands/workflow/review-cycle-fix.md` Phase 2
|
||||
|
||||
## Overview
|
||||
Launch N planning agents (up to MAX_PARALLEL=10) to analyze finding batches concurrently. Each agent outputs a partial plan. Orchestrator aggregates partial plans into unified fix-plan.json.
|
||||
|
||||
## Execution Strategy Determination
|
||||
|
||||
**Strategy Types**:
|
||||
|
||||
| Strategy | When to Use | Stage Structure |
|
||||
|----------|-------------|-----------------|
|
||||
| **Parallel** | All groups independent, different files | Single stage, all groups in parallel |
|
||||
| **Serial** | Strong dependencies, shared resources | Multiple stages, one group per stage |
|
||||
| **Hybrid** | Mixed dependencies | Multiple stages, parallel within stages |
|
||||
|
||||
**Dependency Detection**:
|
||||
- Shared file modifications
|
||||
- Utility creation + usage patterns
|
||||
- Test dependency chains
|
||||
- Risk level clustering (high-risk groups isolated)
|
||||
|
||||
## Phase 2: Parallel Planning Coordination (Orchestrator)
|
||||
|
||||
```javascript
|
||||
const MAX_PARALLEL = 10;
|
||||
const partialPlans = [];
|
||||
|
||||
// Process batches in chunks of MAX_PARALLEL
|
||||
for (let i = 0; i < batches.length; i += MAX_PARALLEL) {
|
||||
const chunk = batches.slice(i, i + MAX_PARALLEL);
|
||||
const agentIds = [];
|
||||
|
||||
// Step 1: Spawn agents in parallel
|
||||
for (const batch of chunk) {
|
||||
const agentId = spawn_agent({
|
||||
message: planningPrompt(batch) // See Planning Agent template below
|
||||
});
|
||||
agentIds.push({ agentId, batch });
|
||||
}
|
||||
|
||||
console.log(`Spawned ${agentIds.length} planning agents...`);
|
||||
|
||||
// Step 2: Batch wait for all agents in this chunk
|
||||
const chunkResults = wait({
|
||||
ids: agentIds.map(a => a.agentId),
|
||||
timeout_ms: 600000 // 10 minutes
|
||||
});
|
||||
|
||||
// Step 3: Collect results from this chunk
|
||||
for (const { agentId, batch } of agentIds) {
|
||||
if (chunkResults.status[agentId].completed) {
|
||||
const partialPlan = JSON.parse(Read(`${sessionDir}/partial-plan-${batch.batch_id}.json`));
|
||||
partialPlans.push(partialPlan);
|
||||
console.log(`Batch ${batch.batch_id} planning completed`);
|
||||
} else {
|
||||
console.log(`Batch ${batch.batch_id} planning failed/timed out`);
|
||||
}
|
||||
}
|
||||
|
||||
// Step 4: Cleanup agents in this chunk
|
||||
agentIds.forEach(({ agentId }) => close_agent({ id: agentId }));
|
||||
}
|
||||
|
||||
// Aggregate partial plans → fix-plan.json
|
||||
let groupCounter = 1;
|
||||
const groupIdMap = new Map();
|
||||
|
||||
for (const partial of partialPlans) {
|
||||
for (const group of partial.groups) {
|
||||
const newGroupId = `G${groupCounter}`;
|
||||
groupIdMap.set(`${partial.batch_id}:${group.group_id}`, newGroupId);
|
||||
aggregatedPlan.groups.push({ ...group, group_id: newGroupId, progress_file: `fix-progress-${groupCounter}.json` });
|
||||
groupCounter++;
|
||||
}
|
||||
}
|
||||
|
||||
// Merge timelines, resolve cross-batch conflicts (shared files → serialize)
|
||||
let stageCounter = 1;
|
||||
for (const partial of partialPlans) {
|
||||
for (const stage of partial.timeline) {
|
||||
aggregatedPlan.timeline.push({
|
||||
...stage, stage_id: stageCounter,
|
||||
groups: stage.groups.map(gid => groupIdMap.get(`${partial.batch_id}:${gid}`))
|
||||
});
|
||||
stageCounter++;
|
||||
}
|
||||
}
|
||||
|
||||
// Write aggregated plan + initialize progress files
|
||||
Write(`${sessionDir}/fix-plan.json`, JSON.stringify(aggregatedPlan, null, 2));
|
||||
for (let i = 1; i <= aggregatedPlan.groups.length; i++) {
|
||||
Write(`${sessionDir}/fix-progress-${i}.json`, JSON.stringify(initProgressFile(aggregatedPlan.groups[i-1]), null, 2));
|
||||
}
|
||||
```
|
||||
|
||||
## Planning Agent Template (Batch Mode)
|
||||
|
||||
```javascript
|
||||
// Spawn planning agent for a batch
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## Task Objective
|
||||
Analyze code review findings in batch ${batch.batch_id} and generate **partial** execution plan.
|
||||
|
||||
## Input Data
|
||||
Review Session: ${reviewId}
|
||||
Fix Session ID: ${fixSessionId}
|
||||
Batch ID: ${batch.batch_id}
|
||||
Batch Findings: ${batch.findings.length}
|
||||
|
||||
Findings:
|
||||
${JSON.stringify(batch.findings, null, 2)}
|
||||
|
||||
Project Context:
|
||||
- Structure: ${projectStructure}
|
||||
- Test Framework: ${testFramework}
|
||||
- Git Status: ${gitStatus}
|
||||
|
||||
## Output Requirements
|
||||
|
||||
### 1. partial-plan-${batch.batch_id}.json
|
||||
Generate partial execution plan with structure:
|
||||
{
|
||||
"batch_id": ${batch.batch_id},
|
||||
"groups": [...], // Groups created from batch findings (use local IDs: G1, G2, ...)
|
||||
"timeline": [...], // Local timeline for this batch only
|
||||
"metadata": {
|
||||
"findings_count": ${batch.findings.length},
|
||||
"groups_count": N,
|
||||
"created_at": "ISO-8601-timestamp"
|
||||
}
|
||||
}
|
||||
|
||||
**Key Generation Rules**:
|
||||
- **Groups**: Create groups with local IDs (G1, G2, ...) using intelligent grouping (file+dimension+root cause)
|
||||
- **Timeline**: Define stages for this batch only (local dependencies within batch)
|
||||
- **Progress Files**: DO NOT generate fix-progress-*.json here (orchestrator handles after aggregation)
|
||||
|
||||
## Analysis Requirements
|
||||
|
||||
### Intelligent Grouping Strategy
|
||||
Group findings using these criteria (in priority order):
|
||||
|
||||
1. **File Proximity**: Findings in same file or related files
|
||||
2. **Dimension Affinity**: Same dimension (security, performance, etc.)
|
||||
3. **Root Cause Similarity**: Similar underlying issues
|
||||
4. **Fix Approach Commonality**: Can be fixed with similar approach
|
||||
|
||||
**Grouping Guidelines**:
|
||||
- Optimal group size: 2-5 findings per group
|
||||
- Avoid cross-cutting concerns in same group
|
||||
- Consider test isolation (different test suites → different groups)
|
||||
- Balance workload across groups for parallel execution
|
||||
|
||||
### Execution Strategy Determination (Local Only)
|
||||
|
||||
**Parallel Mode**: Use when groups are independent, no shared files
|
||||
**Serial Mode**: Use when groups have dependencies or shared resources
|
||||
**Hybrid Mode**: Use for mixed dependency graphs (recommended for most cases)
|
||||
|
||||
**Dependency Analysis**:
|
||||
- Identify shared files between groups
|
||||
- Detect test dependency chains
|
||||
- Evaluate risk of concurrent modifications
|
||||
|
||||
### Risk Assessment
|
||||
|
||||
For each group, evaluate:
|
||||
- **Complexity**: Based on code structure, file size, existing tests
|
||||
- **Impact Scope**: Number of files affected, API surface changes
|
||||
- **Rollback Feasibility**: Ease of reverting changes if tests fail
|
||||
|
||||
### Test Strategy
|
||||
|
||||
For each group, determine:
|
||||
- **Test Pattern**: Glob pattern matching affected tests
|
||||
- **Pass Criteria**: All tests must pass (100% pass rate)
|
||||
- **Test Command**: Infer from project (package.json, pytest.ini, etc.)
|
||||
|
||||
## Output Files
|
||||
|
||||
Write to ${sessionDir}:
|
||||
- ./partial-plan-${batch.batch_id}.json
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finalizing outputs:
|
||||
- All batch findings assigned to exactly one group
|
||||
- Group dependencies (within batch) correctly identified
|
||||
- Timeline stages respect local dependencies
|
||||
- Test patterns are valid and specific
|
||||
- Risk assessments are realistic
|
||||
`
|
||||
});
|
||||
|
||||
// Wait for completion
|
||||
const result = wait({
|
||||
ids: [agentId],
|
||||
timeout_ms: 600000 // 10 minutes
|
||||
});
|
||||
|
||||
// Cleanup
|
||||
close_agent({ id: agentId });
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- Files: `partial-plan-{batch-id}.json` (per agent), `fix-plan.json` (aggregated), `fix-progress-*.json` (initialized)
|
||||
- Progress: Mark Phase 7 completed, Phase 8 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 8: Fix Execution](08-fix-execution.md).
|
||||
239
.codex/skills/review-cycle/phases/08-fix-execution.md
Normal file
239
.codex/skills/review-cycle/phases/08-fix-execution.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Phase 8: Fix Execution
|
||||
|
||||
> Source: `commands/workflow/review-cycle-fix.md` Phase 3
|
||||
|
||||
## Overview
|
||||
Stage-based execution using aggregated fix-plan.json timeline. Each group gets a cli-execute-agent that applies fixes, runs tests, and commits on success or rolls back on failure.
|
||||
|
||||
## Conservative Test Verification
|
||||
|
||||
**Test Strategy** (per fix):
|
||||
|
||||
```javascript
|
||||
// 1. Identify affected tests
|
||||
const testPattern = identifyTestPattern(finding.file);
|
||||
// e.g., "tests/auth/**/*.test.*" for src/auth/service.ts
|
||||
|
||||
// 2. Run tests
|
||||
const result = await runTests(testPattern);
|
||||
|
||||
// 3. Evaluate
|
||||
if (result.passRate < 100%) {
|
||||
// Rollback
|
||||
await gitCheckout(finding.file);
|
||||
|
||||
// Retry with failure context
|
||||
if (attempts < maxIterations) {
|
||||
const fixContext = analyzeFailure(result.stderr);
|
||||
regenerateFix(finding, fixContext);
|
||||
retry();
|
||||
} else {
|
||||
markFailed(finding.id);
|
||||
}
|
||||
} else {
|
||||
// Commit
|
||||
await gitCommit(`Fix: ${finding.title} [${finding.id}]`);
|
||||
markFixed(finding.id);
|
||||
}
|
||||
```
|
||||
|
||||
**Pass Criteria**: 100% test pass rate (no partial fixes)
|
||||
|
||||
## Phase 3: Execution Orchestration (Orchestrator)
|
||||
|
||||
- Load fix-plan.json timeline stages
|
||||
- For each stage:
|
||||
- If parallel mode: Spawn all group agents, batch wait
|
||||
- If serial mode: Spawn groups sequentially with wait between each
|
||||
- Assign agent IDs (agents update their fix-progress-{N}.json)
|
||||
- Handle agent failures gracefully (mark group as failed, continue)
|
||||
- Advance to next stage only when current stage complete
|
||||
- Lifecycle: spawn_agent → wait → close_agent per group/batch
|
||||
|
||||
## Execution Agent Template (Per Group)
|
||||
|
||||
```javascript
|
||||
// Spawn execution agent for a group
|
||||
const execAgentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## Task Objective
|
||||
Execute fixes for code review findings in group ${group.group_id}. Update progress file in real-time with flow control tracking.
|
||||
|
||||
## Assignment
|
||||
- Group ID: ${group.group_id}
|
||||
- Group Name: ${group.group_name}
|
||||
- Progress File: ${sessionDir}/${group.progress_file}
|
||||
- Findings Count: ${group.findings.length}
|
||||
- Max Iterations: ${maxIterations} (per finding)
|
||||
|
||||
## Fix Strategy
|
||||
${JSON.stringify(group.fix_strategy, null, 2)}
|
||||
|
||||
## Risk Assessment
|
||||
${JSON.stringify(group.risk_assessment, null, 2)}
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Initialization (Before Starting)
|
||||
|
||||
1. Read ${group.progress_file} to load initial state
|
||||
2. Update progress file:
|
||||
- assigned_agent: "${agentId}"
|
||||
- status: "in-progress"
|
||||
- started_at: Current ISO 8601 timestamp
|
||||
- last_update: Current ISO 8601 timestamp
|
||||
3. Write updated state back to ${group.progress_file}
|
||||
|
||||
### Main Execution Loop
|
||||
|
||||
For EACH finding in ${group.progress_file}.findings:
|
||||
|
||||
#### Step 1: Analyze Context
|
||||
|
||||
**Before Step**:
|
||||
- Update finding: status→"in-progress", started_at→now()
|
||||
- Update current_finding: Populate with finding details, status→"analyzing", action→"Reading file and understanding code structure"
|
||||
- Update phase→"analyzing"
|
||||
- Update flow_control: Add "analyze_context" step to implementation_approach (status→"in-progress"), set current_step→"analyze_context"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Read file: finding.file
|
||||
- Understand code structure around line: finding.line
|
||||
- Analyze surrounding context (imports, dependencies, related functions)
|
||||
- Review recommendations: finding.recommendations
|
||||
|
||||
**After Step**:
|
||||
- Update flow_control: Mark "analyze_context" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
#### Step 2: Apply Fix
|
||||
|
||||
**Before Step**:
|
||||
- Update current_finding: status→"fixing", action→"Applying code changes per recommendations"
|
||||
- Update phase→"fixing"
|
||||
- Update flow_control: Add "apply_fix" step to implementation_approach (status→"in-progress"), set current_step→"apply_fix"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Use Edit tool to implement code changes per finding.recommendations
|
||||
- Follow fix_strategy.approach
|
||||
- Maintain code style and existing patterns
|
||||
|
||||
**After Step**:
|
||||
- Update flow_control: Mark "apply_fix" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
#### Step 3: Test Verification
|
||||
|
||||
**Before Step**:
|
||||
- Update current_finding: status→"testing", action→"Running test suite to verify fix"
|
||||
- Update phase→"testing"
|
||||
- Update flow_control: Add "run_tests" step to implementation_approach (status→"in-progress"), set current_step→"run_tests"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Run tests using fix_strategy.test_pattern
|
||||
- Require 100% pass rate
|
||||
- Capture test output
|
||||
|
||||
**On Test Failure**:
|
||||
- Git rollback: \`git checkout -- \${finding.file}\`
|
||||
- Increment finding.attempts
|
||||
- Update flow_control: Mark "run_tests" step as "failed" with completed_at→now()
|
||||
- Update errors: Add entry (finding_id, error_type→"test_failure", message, timestamp)
|
||||
- If finding.attempts < ${maxIterations}:
|
||||
- Reset flow_control: implementation_approach→[], current_step→null
|
||||
- Retry from Step 1
|
||||
- Else:
|
||||
- Update finding: status→"completed", result→"failed", error_message→"Max iterations reached", completed_at→now()
|
||||
- Update summary counts, move to next finding
|
||||
|
||||
**On Test Success**:
|
||||
- Update flow_control: Mark "run_tests" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
- Proceed to Step 4
|
||||
|
||||
#### Step 4: Commit Changes
|
||||
|
||||
**Before Step**:
|
||||
- Update current_finding: status→"committing", action→"Creating git commit for successful fix"
|
||||
- Update phase→"committing"
|
||||
- Update flow_control: Add "commit_changes" step to implementation_approach (status→"in-progress"), set current_step→"commit_changes"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Git commit: \`git commit -m "fix(${finding.dimension}): ${finding.title} [${finding.id}]"\`
|
||||
- Capture commit hash
|
||||
|
||||
**After Step**:
|
||||
- Update finding: status→"completed", result→"fixed", commit_hash→<captured>, test_passed→true, completed_at→now()
|
||||
- Update flow_control: Mark "commit_changes" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
#### After Each Finding
|
||||
|
||||
- Update summary: Recalculate counts (pending/in_progress/fixed/failed) and percent_complete
|
||||
- If all findings completed: Clear current_finding, reset flow_control
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
### Final Completion
|
||||
|
||||
When all findings processed:
|
||||
- Update status→"completed", phase→"done", summary.percent_complete→100.0
|
||||
- Update last_update→now(), write final state to ${group.progress_file}
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
### Progress File Updates
|
||||
- **MUST update after every significant action** (before/after each step)
|
||||
- **Always maintain complete structure** - never write partial updates
|
||||
- **Use ISO 8601 timestamps** - e.g., "2025-01-25T14:36:00Z"
|
||||
|
||||
### Flow Control Format
|
||||
Follow action-planning-agent flow_control.implementation_approach format:
|
||||
- step: Identifier (e.g., "analyze_context", "apply_fix")
|
||||
- action: Human-readable description
|
||||
- status: "pending" | "in-progress" | "completed" | "failed"
|
||||
- started_at: ISO 8601 timestamp or null
|
||||
- completed_at: ISO 8601 timestamp or null
|
||||
|
||||
### Error Handling
|
||||
- Capture all errors in errors[] array
|
||||
- Never leave progress file in invalid state
|
||||
- Always write complete updates, never partial
|
||||
- On unrecoverable error: Mark group as failed, preserve state
|
||||
|
||||
## Test Patterns
|
||||
Use fix_strategy.test_pattern to run affected tests:
|
||||
- Pattern: ${group.fix_strategy.test_pattern}
|
||||
- Command: Infer from project (npm test, pytest, etc.)
|
||||
- Pass Criteria: 100% pass rate required
|
||||
`
|
||||
});
|
||||
|
||||
// Wait for completion
|
||||
const execResult = wait({
|
||||
ids: [execAgentId],
|
||||
timeout_ms: 1200000 // 20 minutes per group
|
||||
});
|
||||
|
||||
// Cleanup
|
||||
close_agent({ id: execAgentId });
|
||||
```
|
||||
|
||||
## Output
|
||||
- Files: fix-progress-{N}.json (updated per group), git commits
|
||||
- Progress: Mark Phase 8 completed, Phase 9 in_progress
|
||||
|
||||
## Next Phase
|
||||
Return to orchestrator, then auto-continue to [Phase 9: Fix Completion](09-fix-completion.md).
|
||||
141
.codex/skills/review-cycle/phases/09-fix-completion.md
Normal file
141
.codex/skills/review-cycle/phases/09-fix-completion.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Phase 9: Fix Completion
|
||||
|
||||
> Source: `commands/workflow/review-cycle-fix.md` Phase 4 + Phase 5
|
||||
|
||||
## Overview
|
||||
Aggregate fix results, generate summary report, update history, and optionally complete workflow session.
|
||||
|
||||
## Phase 4: Completion & Aggregation (Orchestrator)
|
||||
|
||||
- Collect final status from all fix-progress-{N}.json files
|
||||
- Generate fix-summary.md with timeline and results
|
||||
- Update fix-history.json with new session entry
|
||||
- Remove active-fix-session.json
|
||||
- Progress tracking: Mark all phases done
|
||||
- Output summary to user
|
||||
|
||||
## Phase 5: Session Completion (Orchestrator)
|
||||
|
||||
- If all findings fixed successfully (no failures):
|
||||
- Prompt user: "All fixes complete. Complete workflow session? [Y/n]"
|
||||
- If confirmed: Archive session with lessons learned
|
||||
- If partial success (some failures):
|
||||
- Output: "Some findings failed. Review fix-summary.md before completing session."
|
||||
- Do NOT auto-complete session
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Batching Failures (Phase 1.5)
|
||||
|
||||
- Invalid findings data -> Abort with error message
|
||||
- Empty batches after grouping -> Warn and skip empty batches
|
||||
|
||||
### Planning Failures (Phase 2)
|
||||
|
||||
- Planning agent timeout -> Mark batch as failed, continue with other batches
|
||||
- Partial plan missing -> Skip batch, warn user
|
||||
- Agent crash -> Collect available partial plans, proceed with aggregation
|
||||
- All agents fail -> Abort entire fix session with error
|
||||
- Aggregation conflicts -> Apply conflict resolution (serialize conflicting groups)
|
||||
|
||||
### Execution Failures (Phase 3)
|
||||
|
||||
- Agent crash -> Mark group as failed, continue with other groups
|
||||
- Test command not found -> Skip test verification, warn user
|
||||
- Git operations fail -> Abort with error, preserve state
|
||||
|
||||
### Rollback Scenarios
|
||||
|
||||
- Test failure after fix -> Automatic `git checkout` rollback
|
||||
- Max iterations reached -> Leave file unchanged, mark as failed
|
||||
- Unrecoverable error -> Rollback entire group, save checkpoint
|
||||
|
||||
## Progress Tracking Structures
|
||||
|
||||
### Initialization (after Phase 1.5 batching)
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization → completed
|
||||
Phase 1.5: Intelligent Batching → completed
|
||||
Phase 2: Parallel Planning → in_progress
|
||||
→ Batch 1: 4 findings (auth.ts:security) → pending
|
||||
→ Batch 2: 3 findings (query.ts:security) → pending
|
||||
→ Batch 3: 2 findings (config.ts:quality) → pending
|
||||
Phase 3: Execution → pending
|
||||
Phase 4: Completion → pending
|
||||
```
|
||||
|
||||
### During Planning (parallel agents running)
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization → completed
|
||||
Phase 1.5: Intelligent Batching → completed
|
||||
Phase 2: Parallel Planning → in_progress
|
||||
→ Batch 1: 4 findings (auth.ts:security) → completed
|
||||
→ Batch 2: 3 findings (query.ts:security) → in_progress
|
||||
→ Batch 3: 2 findings (config.ts:quality) → in_progress
|
||||
Phase 3: Execution → pending
|
||||
Phase 4: Completion → pending
|
||||
```
|
||||
|
||||
### During Execution
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization → completed
|
||||
Phase 1.5: Intelligent Batching → completed
|
||||
Phase 2: Parallel Planning (3 batches → 5 groups) → completed
|
||||
Phase 3: Execution → in_progress
|
||||
→ Stage 1: Parallel execution (3 groups) → completed
|
||||
• Group G1: Auth validation (2 findings) → completed
|
||||
• Group G2: Query security (3 findings) → completed
|
||||
• Group G3: Config quality (1 finding) → completed
|
||||
→ Stage 2: Serial execution (1 group) → in_progress
|
||||
• Group G4: Dependent fixes (2 findings) → in_progress
|
||||
Phase 4: Completion → pending
|
||||
```
|
||||
|
||||
### Update Rules
|
||||
|
||||
- Add batch items dynamically during Phase 1.5
|
||||
- Mark batch items completed as parallel agents return results
|
||||
- Add stage/group items dynamically after Phase 2 plan aggregation
|
||||
- Mark completed immediately after each group finishes
|
||||
- Update parent phase status when all child items complete
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
After completion, ask user whether to expand into issues (test/enhance/refactor/doc). For selected items, create structured issues with summary and dimension context.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Leverage Parallel Planning**: For 10+ findings, parallel batching significantly reduces planning time
|
||||
2. **Tune Batch Size**: Use `--batch-size` to control granularity (smaller batches = more parallelism, larger = better grouping context)
|
||||
3. **Conservative Approach**: Test verification is mandatory - no fixes kept without passing tests
|
||||
4. **Parallel Efficiency**: MAX_PARALLEL=10 for planning agents, 3 concurrent execution agents per stage
|
||||
5. **Resume Support**: Fix sessions can resume from checkpoints after interruption
|
||||
6. **Manual Review**: Always review failed fixes manually - may require architectural changes
|
||||
7. **Incremental Fixing**: Start with small batches (5-10 findings) before large-scale fixes
|
||||
|
||||
## Related Commands
|
||||
|
||||
### View Fix Progress
|
||||
Use `ccw view` to open the workflow dashboard in browser:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
|
||||
### Re-run Fix Pipeline
|
||||
```
|
||||
review-cycle --fix ...
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- Files: fix-summary.md, fix-history.json
|
||||
- State: active-fix-session.json removed
|
||||
- Optional: workflow session completed and archived
|
||||
|
||||
## Completion
|
||||
|
||||
Review Cycle fix pipeline complete. Review fix-summary.md for results.
|
||||
Reference in New Issue
Block a user