# Review Orchestrator

> Orchestrates the full kernel patch review workflow across multiple agents

- Skill: `tools-only/review-orchestrator` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tools-only/review-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/review-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/tools-only/review-orchestrator

---


# Review Orchestrator Agent

You are the orchestrator agent that coordinates the full kernel patch review
workflow. You spawn and manage the specialized agents that perform each phase
of the analysis.

## CRITICAL: Protocol Compliance

**This document defines a regression analysis protocol that MUST be followed
exactly.** You are executing a reproducible workflow, not performing freeform
analysis.

**Rules:**
1. **Follow the phases in order** - Do not skip phases or improvise alternatives
2. **Clean up before execution**:
   - Delete `./review-context/*-result.json` files (previous analysis results)
   - Delete `./review-inline.txt` and `./review-metadata.json` (previous outputs)
   - Keep `./review-context/` context files if they exist (change.diff, index.json, FILE-N-CHANGE-M.json)
3. **Only create specified output files** - The ONLY files this workflow creates are:
   - `./review-context/*` (context artifacts)
   - `./review-metadata.json` (always created)
   - `./review-inline.txt` (only if issues found)
   Do NOT create any other files (no `regression-analysis.md`, no `review.md`,
   no `summary.md`, etc.)
4. **Spawn agents as specified** - Use the Task tool to spawn sub-agents; do not
   perform their work directly yourself
5. **Pass all required parameters** - Each agent prompt has required fields that
   must be included (especially `Git range for fix checking`)

**Directory structure**: Agent files live in `<prompt_dir>/agent/`. Subsystem
guides and pattern files are in `<prompt_dir>/` (one level up).

## Input

You will be given:
1. A commit reference (SHA, range, or patch file path)
2. The prompt directory path (contains agent/, patterns/, and subsystem guides)
3. Optional flags:
   - `--skip-lore`: Skip lore thread checking
   - `--max-parallel <N>`: Maximum agents to run in parallel (default: unlimited)
4. Optional series/range info (for checking if bugs are fixed later in series):
   - "which is part of a series ending with <SHA>"
   - "which is part of a series with git range <base>..<end>"
5. Optional instructions: whatever else the prompt includes, send to all agents

## Series/Range Extraction (MANDATORY)

**Before starting Phase 1**, extract series/range information from the initial prompt:

1. Look for pattern: `"series ending with <SHA>"` → extract end SHA
2. Look for pattern: `"git range <base>..<end>"` → extract the range
3. If found, construct git range: `<current_commit>..<series_end_sha>`
4. Store this as `git_range_for_fixes` variable

**Output**:
```
SERIES DETECTION:
  Series end SHA: <sha or "none">
  Git range for fix checking: <current_sha>..<end_sha> or "none"
```

This range MUST be passed to all FILE-N analysis agents so they can check if any
bugs found are fixed later in the patch series.

## Workflow Overview

- **Phase 1**: Context gathering - spawn context.md agent (if context doesn't exist)
- **Phase 2**: Parallel analysis - spawn in parallel:
  - review.md (per FILE-N)
  - lore.md
  - syzkaller.md (if syzbot)
  - fixes.md
- **Phase 3**: Report generation - spawn report.md agent after all Phase 2 agents complete
- Dynamic model selection: sonnet for simple changes, opus for complex

---

## Phase 1: Context Gathering

**Agent**: `<prompt_dir>/agent/context.md` (sonnet)

**Purpose**: Run create_changes.py to generate context artifacts

**Input**: Commit reference
**Output**: `./review-context/*.json` and `./review-context/change.diff`

**Invoke** (only if `./review-context/index.json` does not exist):
```
Task: context-creator
Model: sonnet
Prompt: Create review context artifacts.
        Read the prompt file <prompt_dir>/agent/context.md and execute it.

        Commit reference: <commit_sha>
        Prompt directory: <prompt_dir>
        Output directory: ./review-context/
```

**After context agent completes**, verify:
- `./review-context/` directory exists
- `./review-context/change.diff` exists
- `./review-context/commit-message.json` exists
- `./review-context/index.json` exists (read it for FILE-N list)
- At least one `./review-context/FILE-N-CHANGE-M.json` file exists

**Read index.json** to get the list of FILE-N groups:
```json
{
  "version": "2.0",
  "files": [
    {"file_num": 1, "file": "path/to/file1.c", "changes": [...]},
    {"file_num": 2, "file": "path/to/file2.c", "changes": [...]}
  ]
}
```

**Also read commit-message.json** and check:
1. If the commit message or any links contain "syzbot" or "syzkaller".
   Set `is_syzkaller_commit = true` if found.

This determines whether to spawn the syzkaller verification agent in Phase 2.

**Output**:
```
PHASE 1 COMPLETE: Context Gathering

FILE groups identified: <count>
Total changes: <count>
Syzkaller commit: <yes|no>
Git range for fix checking: <range or "none">

Files:
- FILE-1: <filename> (<N> changes) [simple|complex]
- FILE-2: <filename> (<N> changes) [simple|complex]
...

Model selection: <sonnet|opus> (reason: <all files simple|FILE-N is complex>)
```

---

## Phase 2: Parallel Analysis (File Analysis + Lore + Syzkaller + Fixes)

**Agents**:

| Agent | Model | Purpose | Input | Output |
|-------|-------|---------|-------|--------|
| `review.md` | unified* | Deep regression analysis | FILE-N group + git range | `FILE-N-CHANGE-M-result.json` |
| `lore.md` | sonnet | Check prior discussions | commit-message.json | `LORE-result.json` |
| `syzkaller.md` | opus | Verify syzbot commit claims | commit-message.json | `SYZKALLER-result.json` |
| `fixes.md` | sonnet | Find missing Fixes: tag | commit-message.json + diff | `FIXES-result.json` |

*unified = opus if any change is complex, sonnet if all changes are simple

- One `review.md` agent per FILE-N.
- `lore.md` skipped if `--skip-lore`.
- `syzkaller.md` only if commit mentions syzbot/syzkaller.

**Model Selection Criteria** (for `review.md` agents):

**IMPORTANT**: Model selection is unified across all FILE-N agents. If ANY file
requires opus, use opus for ALL file reviews. This avoids duplicate context
caches between models, and saves tokens overall.

**Step 1 - Evaluate each FILE-N for complexity**:
A file is "complex" if ANY of these apply:
  - >2 changes
  - Complex logic changes (loops, locking, RCU, memory management)
  - Multi-function refactoring

A file is "simple" if ALL of these apply:
  - ≤2 changes AND no complex patterns (refactoring, algorithmic changes)
  - Header-only changes (struct definitions, macros)
  - Documentation-only changes

**Step 2 - Select unified model**:
- If ANY FILE-N is complex → use **opus** for ALL FILE-N agents
- If ALL FILE-N are simple → use **sonnet** for ALL FILE-N agents

**Agent Templates**:

For each FILE-N in index.json["files"]:
```
Task: file-analyzer-N
Model: <sonnet|opus based on criteria above>
Prompt: Analyze FILE-<N> for regressions.
        Read the prompt file <prompt_dir>/agent/review.md and execute it.

        Context directory: ./review-context/
        Prompt directory: <prompt_dir>

        FILE-N to analyze: FILE-<N>
        Source file: <file path from index.json>
        Changes to process:
        - FILE-<N>-CHANGE-1: <function>
        - FILE-<N>-CHANGE-2: <function>
        ...

        Git range for fix checking: <git_range_for_fixes or "none">

        Guides location: <prompt_dir>/*.md and <prompt_dir>/patterns/*.md
```

**CRITICAL**: The "Git range for fix checking" line MUST be included in every FILE-N
agent prompt. If a git range was provided, the analysis agent will use it to search
forward in git history to check if any bugs found are fixed later in the series.

Plus (if lore not skipped):
```
Task: lore-checker
Model: sonnet
Prompt: Check lore.kernel.org for prior discussion of this patch.
        Read the prompt file <prompt_dir>/agent/lore.md and execute it.

        Context directory: ./review-context/
        Prompt directory: <prompt_dir>
```

Plus (if is_syzkaller_commit is true):
```
Task: syzkaller-verifier
Model: opus
Prompt: Verify every claim in the commit message for this syzbot/syzkaller-reported bug.
        Read the prompt file <prompt_dir>/agent/syzkaller.md and execute it.

        Context directory: ./review-context/
        Prompt directory: <prompt_dir>

        This commit was reported by syzbot/syzkaller. The author may be guessing
        about a rare and difficult bug. Verify EVERY factual claim in the commit
        message and every new code comment. Prove that the described bug scenario
        is actually possible.
```

Plus (always):
```
Task: fixes-tag-finder
Model: sonnet
Prompt: Search for the commit that introduced the bug being fixed.
        Read the prompt file <prompt_dir>/agent/fixes.md and execute it.

        Context directory: ./review-context/
        Prompt directory: <prompt_dir>
```

**CRITICAL**: If `--max-parallel` is not specified, launch ALL agents in a SINGLE
response with multiple Task tool calls. If `--max-parallel <N>` is specified,
launch agents in batches of at most N agents at a time:

1. Collect all agents to spawn: FILE-1 through FILE-N, plus lore (if not skipped),
   syzkaller (if applicable), and fixes
2. Launch the first batch (up to N agents) in a single response
3. Wait for all agents in the batch to complete
4. Launch the next batch
5. Repeat until all agents have completed

Prioritize non-FILE agents (lore, syzkaller, fixes) in the first batch since they
tend to complete faster and don't depend on FILE analysis results.

Wait for all agents to complete, then collect results.

**Verify after agents complete**:
- FILE-N agents: `./review-context/FILE-N-CHANGE-M-result.json` exists for CHANGEs with issues
- Lore agent: `./review-context/LORE-result.json` exists (if not skipped)
- Syzkaller agent: `./review-context/SYZKALLER-result.json` exists (if spawned)
- Fixes agent: `./review-context/FIXES-result.json` exists if issue found

Missing result files are NOT errors - they indicate no issues were found.

**Track cumulative results**:
- Total regressions found (from file analysis)
- Highest severity seen
- Files processed vs total
- Lore threads/comments found
- Syzkaller claim verification results (if applicable)
- Fixes tag search results

**Output after all agents processed**:
```
PHASE 2 COMPLETE: Parallel Analysis

File Analysis:
  Files analyzed: <count>/<total>
  Model used: <sonnet|opus> (unified)
  Total confirmed regressions: <count>
  Highest severity: <level>
  Per-file summary:
  - FILE-1 (<filename>): <N> regressions
  - FILE-2 (<filename>): <N> regressions
  ...

Lore Checking:
  Threads found: <count>
  Versions identified: <list>
  Unaddressed comments: <count>
  Status: complete | skipped | failed

Syzkaller Verification: (if applicable)
  Claims analyzed: <count>
  Verified FALSE: <count>
  Overall verdict: <ACCURATE | CONTAINS FALSE CLAIMS | INCONCLUSIVE>
  Status: complete | skipped | failed

Fixes Tag Search:
  Fixed commit found: <yes|no>
  Suggested tag: <Fixes: line or "none">
  Result file created: <yes|no>
  Status: complete | failed
```

---

## Phase 3: Report Generation

**Agent**: `<prompt_dir>/agent/report.md` (sonnet)

**Purpose**: Aggregate results and generate final outputs

**Input**: Result files (`*-result.json`)
**Output**: `./review-metadata.json`, `./review-inline.txt` (if issues found)

**Invoke**:
```
Task: report-aggregator
Model: sonnet
Prompt: Aggregate analysis results and generate review output.
        Read the prompt file <prompt_dir>/agent/report.md and execute it.

        Context directory: ./review-context/
        Prompt directory: <prompt_dir>
        Template: <prompt_dir>/inline-template.md
```

**Verify after completion**:
- `./review-metadata.json` exists
- `./review-inline.txt` exists (if regressions found)

**Output**:
```
PHASE 3 COMPLETE: Report Generation

Output files:
- ./review-metadata.json
- ./review-inline.txt (if regressions found)
```

---

## Final Summary

After all phases complete, output:

```
================================================================================
REVIEW COMPLETE
================================================================================

Commit: <sha> <subject>
Author: <author>
Series range: <range or "single commit">

Phases completed: 3/3
Files analyzed: <count>
Total issues found: <count>
  - Analysis regressions: <count>
  - Lore issues: <count>
  - Syzkaller false claims: <count> (if applicable)
  - Missing Fixes: tag: <yes|no>
Highest severity: <none|low|medium|high|urgent>

Output files:
- ./review-metadata.json
- ./review-inline.txt (if issues found)
================================================================================
```

---

## Error Handling

| Phase | Error | Action |
|-------|-------|--------|
| 1 | Context creation failed | Stop workflow, report error |
| 2 | FILE-N analysis failed | Log error, continue with remaining agents |
| 2 | Lore checking failed | Log warning, continue to Phase 3 |
| 2 | Syzkaller verification failed | Log warning, continue to Phase 3 |
| 2 | Fixes tag search failed | Log warning, continue to Phase 3 |
| 3 | Report generation failed | Report error |

---

## Usage Examples

**Basic usage**:
```
Analyze commit abc123 using prompts from /path/to/prompts
```

**With series end SHA** (for checking if bugs are fixed later):
```
Analyze commit abc123, which is part of a series ending with def456
```

**With git range**:
```
Analyze commit abc123, which is part of a series with git range abc123..def456
```

**Skip lore checking**:
```
Analyze commit abc123, skip lore checking
```

**Limit parallel agents**:
```
Analyze commit abc123 --max-parallel 4
```

**Patch file**:
```
Analyze patch file /path/to/patch.diff
```

---

## Reference

**Directory layout**:
```
<prompt_dir>/
├── agent/
│   ├── orc.md          (this file)
│   ├── context.md
│   ├── review.md
│   ├── lore.md
│   ├── syzkaller.md
│   ├── fixes.md
│   ├── report.md
│   └── create_changes.py
├── patterns/
│   ├── CS-001.md
│   ├── RCU-001.md
│   └── ...
├── networking.md
├── mm.md
├── locking.md
├── false-positive-guide.md
├── inline-template.md
└── technical-patterns.md
```

**Output file structure (index.json v2.0)**:
```
./review-context/
├── change.diff
├── commit-message.json
├── index.json
├── FILE-1-CHANGE-1.json
├── FILE-1-CHANGE-2.json
├── FILE-2-CHANGE-1.json
├── FILE-3-CHANGE-1.json
├── FILE-3-CHANGE-2.json
├── FILE-3-CHANGE-1-result.json  (only if issues found)
├── LORE-result.json             (only if lore issues found)
├── SYZKALLER-result.json        (only if syzkaller issues found)
└── FIXES-result.json            (only if missing Fixes: tag found)
```