---
name: mach6-review
description: "Run specialized review agents in parallel on a PR (code-reviewer, error-auditor, test-reviewer, completeness-checker, simplifier), post findings, then independently assess each finding to separate genuine issues from nitpicks and false positives. Usage: mach6-review 42 [aspects]"
argument-hint: "<pr-number> [code|errors|tests|completeness|simplify]"
---

# mach6-review — Multi-Agent PR Review

**User input:** $ARGUMENTS

## Global Rules

1. **GitHub as shared memory** — Reviews and assessments are posted as PR comments so any future session can pick up context.
2. **HTML markers** — Use `<!-- mach6-review -->` and `<!-- mach6-assessment -->` as the first line of comment bodies.
3. **No `#N` in comment bodies** — Use "finding 3", "item 3", "stage 2" etc. instead.
4. **Task tracking** — Use the `tasks_update` tool to show progress.
5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks.

**Important: Do NOT fix any issues in this session. Fixes happen via `/skill:mach6-implement`.**

## Step 1: Set up task tracking

```
tasks_update([
  { id: "prepare", title: "Prepare — checkout and gather context", status: "in_progress" },
  { id: "review", title: "Run review agents", status: "pending" },
  { id: "post-review", title: "Post review findings", status: "pending" },
  { id: "assess", title: "Independent assessment", status: "pending" },
  { id: "post-assess", title: "Post assessment", status: "pending" },
  { id: "summary", title: "Present CLI summary", status: "pending" }
])
```

## Step 2: Parse input

Extract:
- **PR number** (required)
- **Review aspects** (optional) — if specified, only run matching agents

## Step 3: Prepare

```bash
gh pr checkout <pr-number>
git pull
```

Mark the PR as ready for review (it was opened as a draft by mach6-plan):
```bash
gh pr ready <pr-number>
```

Gather PR context — read ALL comments, not just specific markers:
```bash
gh pr view <pr-number> --json title,body,comments,files
gh pr diff <pr-number>
```

Read the PR description, ALL comments (plans, progress updates, prior reviews, discussion), and the linked issue. This full context must be provided to review agents so they understand what was intended and what has already been discussed.

Update task: prepare → completed, review → in_progress.

## Step 4: Select and run review agents

**Available review agents:**

These agents are **pre-existing agent definitions** shipped with dreb — do not redefine them inline. Reference them by name via the `agent` parameter in `subagent`. Each agent definition already specifies a model with a provider fallback list — the defaults work across providers and are fine for most reviews. Override the model only when there's a good reason (e.g. a particularly complex or security-sensitive review warrants a stronger tier); note that a single-string override discards the fallback list, so prefer provider-prefixed IDs (e.g. `anthropic/claude-opus-4-6`) when overriding.

| Agent | Question | When to run |
|---|---|---|
| `code-reviewer` | "Does this code do what it should, correctly and idiomatically?" | Always |
| `error-auditor` | "What can go wrong silently at runtime?" | If error handling / try-catch / fallback logic touched |
| `test-reviewer` | "What behaviors are untested or poorly tested?" | If test files changed or testable code added |
| `completeness-checker` | "Does this PR deliver everything the linked issue requires?" | If PR links to an issue |
| `simplifier` | "Can this be expressed more clearly without changing behavior?" | Always (runs last, after others) |

**Targeted review:** If the user specified aspects, only run matching agents:
- `code` → code-reviewer
- `errors` → error-auditor
- `tests` → test-reviewer
- `completeness` → completeness-checker
- `simplify` → simplifier

**For each agent**, launch via the `subagent` tool. Run `code-reviewer`, `error-auditor`, `test-reviewer`, and `completeness-checker` in parallel. Run `simplifier` after the others complete.

Provide each agent with:
- The list of changed files with paths
- The PR description and linked issue context
- Instructions to read the actual changed files for full context

All agents use confidence scoring (0-100, only report findings ≥ 80).

Update task: review → completed, post-review → in_progress.

## Step 5: Post review findings

Compile all findings from all agents into a single structured comment:

```bash
cat > /tmp/gh-comment.md << 'MACH6_EOF'
<!-- mach6-review -->
## Code Review

### Critical
<findings with severity: critical, if any>

### Important
<findings with severity: high, if any>

### Suggestions
<findings with severity: medium or low, if any>

### Strengths
<notable positive observations>

**Agents run:** <list of agents>

---
*Reviewed by mach6*
MACH6_EOF
gh pr comment <pr-number> --body-file /tmp/gh-comment.md
```

Save the review comment URL:
```bash
gh pr view <pr-number> --json comments --jq '.comments[-1].url'
```
Extract the numeric comment ID from the URL (the number after `issuecomment-`).

Update task: post-review → completed, assess → in_progress.

## Step 6: Independent assessment

Launch a subagent with `agent: "independent-assessor"`. This is a **pre-existing agent definition** shipped with dreb — it has full codebase read access and uses the strongest available model via its own fallback list. The default is fine for most cases.

**Do NOT use the Sandbox agent for this step** — the Sandbox agent has no codebase access and cannot verify findings against actual code.

Provide the assessor with:
- The full review text
- The PR context (title, body, comments)
- Instructions to **read the actual code** for each finding and verify independently

The assessor classifies each finding as:
- **Genuine issue** — Real problem, should fix before merge. Explain why.
- **Nitpick** — Stylistic, doesn't affect correctness. Explain why it doesn't matter.
- **False positive** — Not actually an issue. Explain why the code is correct.
- **Deferred** — Real issue but out of scope. Should track separately.

If a finding was already addressed in prior commits or PR discussion, classify as false positive with a note.

After classifying all findings, produce an **action plan** listing what to fix, in what order.

**Important guidance on "deferred" classifications:** Test coverage gaps should NOT be automatically deferred. If a PR adds new testable code, tests should ship with it — even if that means adding test infrastructure to a package that lacks it. Only defer tests when the gap is truly unrelated to the PR's changes (e.g., pre-existing untested code that the PR happens to touch). When tests are deferred, the assessor must note whether a tracking issue exists or needs to be created.

Update task: assess → completed, post-assess → in_progress.

## Step 7: Post assessment

```bash
cat > /tmp/gh-comment.md << 'MACH6_EOF'
<!-- mach6-assessment -->
## Review Assessment

<link to review comment>

### Classifications

| Finding | Classification | Reasoning |
|---|---|---|
| <summary> | genuine/nitpick/false-positive/deferred | <1-2 sentences> |

### Action Plan

<numbered list of what to fix, ordered by priority>

---
*Assessment by mach6*
MACH6_EOF
gh pr comment <pr-number> --body-file /tmp/gh-comment.md
```

Update task: post-assess → completed, summary → in_progress.

## Step 8: CLI summary

Present to the user:
- Per-finding breakdown: summary, classification, reasoning
- Counts: genuine, nitpicks, false positives, deferred
- Action plan

If any findings were classified as **deferred**, ask the user if they want to create issues for them:
```bash
cat > /tmp/gh-body.md << 'MACH6_EOF'
<body referencing PR and finding>
MACH6_EOF
gh issue create --title "<title>" --body-file /tmp/gh-body.md
```

Update task: summary → completed.

Suggest next step:
- If genuine issues: `/skill:mach6-implement <pr-number> <finding-numbers>`
- If all clear: `/skill:mach6-publish <pr-number>`
