Claude-Code-Workflow/.codex/skills/review-cycle/phases/01-discovery-initialization.md

# 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('${projectRoot}/.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 ${projectRoot}/.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 ${projectRoot}/.workflow/active/WFS-review-${Date.now()}`);

// Initialize workflow-session.json
const sessionId = `WFS-review-${Date.now()}`;
Write(`${projectRoot}/.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: `${projectRoot}/.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

```
{projectRoot}/.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

```
{projectRoot}/.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).