review-ensemble

What this skill does

# Review Ensemble

Invoke directly with `/review-ensemble` when the user wants cross-model code review by composing /frame (Claude multi-perspective) with Codex (independent model), then aggregating findings at the cross-model boundary.

**Architecture**:
```
review-ensemble
├── /frame Mode 2 (Claude: perspective selection + AgentMap? + investigation + Lens L)
├── Codex CLI (cross-model: independent review, parallel)
└── Cross-model aggregation (Lens L + Codex findings → unified verdict)
```

**Why this composition**: /frame owns Claude-side orchestration — it selects perspectives, maps them to specialized agents, and synthesizes findings into a Lens. Adding Codex provides an independent model family's view. When two independent model families converge on the same issue, that signal is stronger than any single model's confidence score.

## Phase 1: Scope Detection

1. If PR number provided as argument: `gh pr view {NUMBER} --json number,title,headRefName,changedFiles`
2. If no argument: `gh pr view --json number,title,headRefName,changedFiles 2>/dev/null`
3. PR exists: scope = PR diff (`gh pr diff {NUMBER}`)
4. No PR: scope = working tree (`git diff HEAD`)
5. No changes: ask the user what to review

Record scope type, PR number, changed files list, and the **resolved base SHA** (the merge-base or PR base commit the diff is taken against, e.g. `gh pr view {NUMBER} --json baseRefOid -q .baseRefOid`, or `git merge-base HEAD @{u}` / the working-tree `HEAD` for an uncommitted-changes scope). The base SHA + changed-files list is the **pointer** the Codex prompt passes in Phase 2 — Codex re-derives the diff locally with its own git (read-only sandbox, no network), so the full diff content is not inlined.

Also capture diff statistics for context:
```bash
gh pr diff {NUMBER} --stat   # or: git diff HEAD --stat
```

## Phase 2: Parallel Launch

Launch Codex in background FIRST, then invoke /frame (interactive). This maximizes parallelism — Codex runs independently while /frame engages the user for perspective selection.

### Step 1: Launch Codex Reviewers (background)

Check `which codex 2>/dev/null`. If Codex CLI is not found, skip to Step 2 and note in Phase 5 output that this was a single-model review.

Generate a unique suffix for temp files: `SUFFIX=$(openssl rand -hex 4)`

Write review prompt to `/tmp/ensemble_codex_review_${SUFFIX}.txt`, passing a **pointer** to the diff (a git command + changed-files list) so Codex fetches the live diff with its own tools rather than reading an inlined copy:

```
Review the following code changes for correctness, security, and edge cases.

Scope: {PR #{number} — {title} on branch {branch} | working tree changes}
Diff statistics: {diff_stat_output}

## Pointers — read the diff yourself with your own tools
- Diff command: `git diff {base_sha}...HEAD`  (PR scope; for a working-tree scope use `git diff HEAD`)
- Changed files: {file_list}
Run the diff command in this repo to see exactly what changed — the diff is not inlined.

Focus: logic errors, security vulnerabilities, missing error handling, edge cases, API contract violations.

Report each finding as:
- [{severity}] {file}:{line_range} — {description}

Severity: critical | high | medium | low | suggestion
Report only high-confidence findings. Ground all claims in the actual diff — do not speculate about code you have not seen.
End with: VERDICT: approve | needs-attention
```

Run via `Bash(run_in_background: true, timeout: 300000)`. `--color never` + **stdout-only** redirect keeps the events file pure JSONL (the codex banner stays on stderr):
```bash
codex exec --ephemeral --json --color never --skip-git-repo-check --cd {repo_root} -m gpt-5.5 --config model_reasoning_effort="high" --sandbox read-only < /tmp/ensemble_codex_review_${SUFFIX}.txt > /tmp/ensemble_codex_review_events_${SUFFIX}.jsonl
```

`--cd {repo_root}` points Codex's own git/Read at the repo so it can run the diff command against the orchestrator-supplied base SHA; `--sandbox read-only` is kept because `git diff` is a local read needing no network. If Codex's git cannot resolve that base SHA, the diff (and hence the review) comes back empty — the existing "empty extraction = codex failed" guard in Phase 3 surfaces it.

**Optional: codex-adversarial** — If the user requests adversarial review or the change is large/architectural, also launch an adversarial prompt in background using a distinct temp file `/tmp/ensemble_codex_adversarial_${SUFFIX}.txt` (same `SUFFIX`, different filename) so the adversarial runner does not overwrite or re-read the standard review prompt:

```
You are a skeptical reviewer. Challenge the implementation approach and design choices in the following diff.

Scope: {PR #{number} — {title} | working tree changes}

## Pointers — read the diff yourself with your own tools
- Diff command: `git diff {base_sha}...HEAD`  (PR scope; for a working-tree scope use `git diff HEAD`)
- Changed files: {file_list}
Run the diff command in this repo to see exactly what changed — the diff is not inlined.

Question: Is this the right approach? What assumptions does it depend on? Where could this fail under real-world conditions? What second-order effects might occur?

Focus: design flaws, assumption failures, approach alternatives, second-order effects on downstream consumers and deployment.

Severity: critical | high | medium | low | suggestion
Report only high-confidence findings. Ground all claims in the actual diff — do not speculate about code you have not seen.

Report each finding as:
- [{severity}] {file}:{line_range} — {description}

End with: VERDICT: approve | needs-attention
```

Execute with `Bash(run_in_background: true, timeout: 300000)`, to a **distinct** events file so it never collides with the standard-review stream:
```bash
codex exec --ephemeral --json --color never --skip-git-repo-check --cd {repo_root} -m gpt-5.5 --config model_reasoning_effort="high" --sandbox read-only < /tmp/ensemble_codex_adversarial_${SUFFIX}.txt > /tmp/ensemble_codex_adversarial_events_${SUFFIX}.jsonl
```

### Step 2: Invoke /frame Mode 2 (foreground, interactive)

Check if the `prothesis:frame` skill is available. If not available (epistemic-protocols plugin not installed), fall back to the **manual review mode** described in the Fallback section below.

If available:
```
Skill("prothesis:frame", args: "Assemble a code review team for these changes. Scope: {scope_description}. Changed files: {file_list}. [select_all_perspectives]")
```

/frame will:
1. **Phase 0**: Mission Brief (Extension — explicit argument provided)
2. **Phase 1**: Context gathering (codebase exploration)
3. **Phase 2**: Perspective selection (Extension — select_all_perspectives: auto-select all proposed lenses)
4. **Phase 3**: AgentMap? → map perspectives to available agents → team investigation
5. **Phase 4**: Cross-dialogue + synthesis → **Lens L** (convergence, divergence, assessment)

The Lens L output contains:
- **Convergence**: Where Claude perspectives agree — robust findings
- **Divergence**: Where perspectives disagree — different values or evidence
- **Assessment**: Integrated analysis with attribution to contributing perspectives

## Phase 3: Collection

After /frame completes (Lens L in context), the background Codex task will send a completion notification automatically. When the notification arrives:

1. Each launched codex stream is pure JSONL (`--json` on stdout) in its own events file: the standard review in `/tmp/ensemble_codex_review_events_${SUFFIX}.jsonl`, and — if the adversarial path ran — the adversarial in `/tmp/ensemble_codex_adversarial_events_${SUFFIX}.jsonl`.
2. Extract each narrative and **forward it verbatim to the aggregation step — do NOT regex-parse it into findings/verdict**: the consuming agent (an LLM) reads the `[severity] file:line — description` findings and the closing `VERDICT:` line directly from each narrative. Label each by source (the `echo` headers below) so aggregation keeps attrib