/panel-review

name: panel-review
version: 0.1.0
description: Multi-agent panel review of a PR or current-branch diff. Three-model fan-out across Opus, Sonnet, and Haiku. Opus and Sonnet review for regressions, security issues, and bugs; Haiku reviews convention drift, naming, dead code, and comment quality. Discrete severity levels (nit, question, blocker). Sonnet confidence recheck plus draft polish merged into one pass. Dev approval gate before posting via gh pr review. Worktree-isolated. Build log committed to docs/build-logs/panel-review-pr-N.md.

/panel-review — multi-agent code review with a dev approval gate

When to use

Open a PR. Run `/panel-review <PR-number>` from inside the consumer repo to fan three model agents over the diff and produce a structured, dev-approved review comment plus a durable audit-trail build log.

No-arg invocation (`/panel-review`) reviews the current branch's diff vs `main`. Useful when you want a panel pass before opening a PR.

Skip for: trivial doc-only PRs (overhead exceeds value), out-of-band reviews where you just want a quick scan rather than a posted review.

What it produces

Two artifacts:

1. **`<consumer-repo>/docs/build-logs/panel-review-pr-{N}.md`** — durable build log. PR metadata, all three agents' raw findings, the Sonnet confidence recheck adjustments, the polished comment, the dev decision, and a Retro section. Committed to the PR's head branch so it merges with the PR. If a review is rerun on the same PR, append `-{ISO-date}` to the filename rather than overwriting (e.g. `panel-review-pr-5-2026-05-10.md`).

2. **A posted PR review comment** via `gh pr review`, gated on explicit dev approval. One of two shapes only: an approve-with-summary (no blockers) or a request-changes-with-blockers. Questions and nits stay in the build log; they are not posted publicly by default.

Hard rules

1. **Worktree on entry.** The skill creates an isolated worktree on a new branch off the PR's head, then runs `gh pr checkout {N}` inside it. Build log accumulates inside the worktree during the run and is committed to that branch before exit.

2. **3-agent fan-out, parallel.** Spawn Opus, Sonnet, Haiku in parallel via the Task / Agent tool. Wait for all three before synthesizing.

3. **Different prompts for the cheap model.** Opus and Sonnet share a prompt focused on regression risk, security issues, and bugs. Haiku gets a different prompt focused on convention drift, naming, dead code, comment quality, and "does the diff match the PR description." This split keeps Opus and Sonnet's context free of style nits and gives Haiku a scope it handles well.

4. **Discrete severity levels.** Each finding is `nit | question | blocker`. No numeric scoring; LLMs cluster at round numbers and anchor differently across calls. Severity is "how bad if true," not confidence.

5. **Auto-merge by max severity.** Dedupe findings by location and topic; the deduped finding's severity is the highest level any agent assigned it.

6. **Confidence and polish merged into one Sonnet pass.** After fan-out merge, a single fresh-context Sonnet does both:

• For each `blocker`-level finding, verify it's real. False positives demote to `question`, with the demotion and Sonnet's reasoning recorded in the build log. Never silently dropped.
• Format the final review comment for clarity, tone, contradictions, and mis-categorization. One agent, one pass, no authority conflict between confidence and polish.

7. **Dev approval gate before posting.** The polished comment is shown to the dev with three labeled sections (Confirmed blockers, Questions for you/author, Low priority / nits). Dev approves, edits, or rejects. Only on explicit approval does the skill invoke `gh pr review`.

8. **Never auto-posts.** No path through this skill posts to a PR without explicit dev approval. If the gate is unclear, default to not posting.

9. **Build log lives on the PR's branch.** Committed before the worktree is removed so the audit trail merges with the PR. Reruns get an ISO-date suffix.

10. **Retro items live in the build log.** After dev decisions are recorded, the skill writes a "Retro" section listing tests, doc notes, or lint rules the dev might want to add. After worktree cleanup, the skill prompts the dev: *"Want to tackle these now?"* Dev decides whether to act now or later. The skill ends here either way.

11. **Token usage is captured.** Every Agent call's `total_tokens` is recorded. The build log frontmatter has `total_tokens` (sum across all calls); the body has a `## Token usage` section with per-agent and per-phase breakdown. The retro prompt includes the total so the dev has cost context when deciding whether the review was worth it.

12. **Braintrust trace logging is env-var opt-in.** If `BRAINTRUST_API_KEY` is set, the skill logs the PR diff, agent prompts and responses, dev decisions, and the posted comment to the `fdet-panel-review` braintrust project via the SDK at `skills/panel-review/traces.ts`. Without the env var, all trace calls are silent no-ops. Logging failures degrade silently after a one-time stderr warning; they never block the skill's primary work. Nothing braintrust-related (API keys, traces, dataset exports) is committed to the public toolkit repo.

13. **Fork PRs may fail at post time.** `gh pr review` requires write access to the base repo. If the skill is run on a PR from a fork without write access, the post step will fail; the comment is preserved in the build log so it isn't lost.

14. **North-star pre-flight is mandatory but non-blocking.** Phase 0 always runs. Absence of `docs/00-north-star.md` produces a one-line dev warning and a flag in the build log header; presence loads the locked paragraph and forwards it to the fan-out agents as project-identity context. The skill never refuses to run on absence, since toolkits and libraries are legitimate consumers without a north-star.

15. **Privacy default: questions and nits go to chat and build log, not the