# Skillsaw Review Panel > Use when reviewing a skillsaw PR. Dispatches 7 specialist reviewers (Architecture, Python Expert, Security & Supply Chain, QA Engineer, Technical Writer, Ecosystem, Slopinator) as parallel sub-agents by default, then synthesizes a single verdict. Use --serial for cheaper inline execution. - Skill: `stbenjam/skillsaw-review-panel` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add stbenjam/skillsaw-review-panel` - Raw SKILL.md: https://api.skillmd.com/api/skills/stbenjam/skillsaw-review-panel/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - License: Apache-2.0 - Author: stbenjam (https://skillmd.com/u/stbenjam) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/stbenjam/skillsaw-review-panel --- # Review Panel — Multi-Specialist Review **Read-only review — never modify files, never push to any remote.** Run **7 specialist reviewers + 1 arbiter** to review a skillsaw PR. **Parallel (default)** runs independent specialists concurrently. **Serial (`--serial`)** shares context inline to reduce cost, but later specialists see earlier file reads, which can bias them. Keep the panel **advisory**. It does not gate merge. It surfaces findings; the maintainer and PR author review and decide ship. ## Arguments ```text /skillsaw-review-panel [--serial] [] ``` | Argument | Description | |----------|-------------| | `--serial` | Run all specialists inline instead of as parallel sub-agents | | `` | GitHub PR number. Optional — defaults to current branch | ## Specialist Roster | Specialist | Lens | Scope | |---|---|---| | Architecture Reviewer | Check module boundaries, abstraction level, SOLID, cross-file impact, error propagation | [`references/architecture.md`](references/architecture.md) | | Python Expert | Review idiomatic Python, type hints, performance, stdlib usage, packaging conventions | [`references/python-expert.md`](references/python-expert.md) | | Security & Supply Chain Reviewer | Check injection, credential handling, dependency trust, lockfile integrity, build pipeline | [`references/security-supply-chain.md`](references/security-supply-chain.md) | | QA Engineer | Test coverage gaps, untested error paths, edge cases, concrete test suggestions | [`references/qa-engineer.md`](references/qa-engineer.md) | | Technical Writer | Verify documentation accuracy, completeness, consistency with code changes, CLAUDE.md drift | [`references/technical-writer.md`](references/technical-writer.md) | | Ecosystem Reviewer | Review target-tool adoption in the current LLM landscape; core-vs-plugin scope boundary | [`references/ecosystem.md`](references/ecosystem.md) | | Slopinator Reviewer | Catch review-history residue in code comments and AI-authored prose tells in docs, docstrings, and commit messages | [`references/slopinator.md`](references/slopinator.md) | | Panel Arbiter | Handle strategic synthesis, disagreement resolution, final disposition | *(inline, below)* | ## Run the Execution Procedure Follow these steps in order. Do not skip ahead. ### Step 1 — Parse Arguments and Determine Base Ref Parse the argument string. `--serial` sets serial mode. A bare integer is the PR number. Read the repository's `REVIEW.md` before assessing the change. It defines the project-specific review priorities and severity calibration that every panel member and the arbiter must follow. Check what the changes are being compared against: - In the automated workflow, read `/tmp/skillsaw-panel-pr.json` for PR metadata and `/tmp/skillsaw-panel-pr.diff` for the complete patch. Never check out the PR branch or execute its code. - If a PR number is provided outside the automated workflow: use `gh pr view --json baseRefName` and `gh pr diff ` without checking out the PR branch. - If no PR number: review the current branch. Find the merge base using the first of `upstream/main`, `origin/main`, `upstream/master`, `origin/master` that exists. If no base ref can be determined, throw an error and exit. For a local branch review, read the diff once: ```bash git diff ...HEAD ``` Also run `git diff ...HEAD --stat` for a file-level summary. ### Step 2 — Check for Prior Panel Reviews (PR only) Skip this step if no PR number is known. Check for previous panel review comments: In the automated workflow, inspect the `comments` array in `/tmp/skillsaw-panel-pr.json`. Outside it, run: ```bash gh pr view --json comments --jq '.comments[] | select(.body | contains("Generated by skillsaw-review-panel")) | {createdAt, body}' ``` Count the matching comments, plus one, for this run's round number — carry it to Step 6. If prior reviews exist, note which findings have been addressed by subsequent commits and which remain unresolved. Avoid re-raising resolved issues. ### Step 3 — Dispatch Specialists Sub-agents and serial reviewers are read-only — no file modifications, no `git push` or force-push to any remote, and no `gh` write commands (`gh pr comment`, `gh pr edit`, `gh issue`, or direct API mutations). Only the main agent posts the final verdict. #### Findings format Each specialist must produce findings in this format: - **Severity**: `BLOCKING` | `SUGGESTION` | `NOTE` - **File:line** — include the reference when applicable - **Finding** — write a description - **Recommended action** — make it explicit If no issues found, say so and list what was checked. **Follow this severity calibration:** - `BLOCKING`: Correctness regressions, security vulnerabilities, architectural faults that compound, (for the Ecosystem Reviewer) a scope violation that warrants redirect-to-plugin, or (for the Slopinator) review history and generated prose left in shipped text. Always include explicit rationale. - `SUGGESTION`: Substantive feedback that improves the code but is not a correctness issue. Keep this the default for real feedback. - `NOTE`: One-line polish, style nits, minor improvements. #### Proportional review Every specialist and the arbiter must accept practical rule disabling, suppressions, or bulk file exclusions for extreme false-positive cases. Avoid complex special-case code and exhaustive tests where likelihood and impact do not justify maintenance cost. Before raising an edge case, explain the affected use, impact, and why configuration is insufficient. Common false positives, broken supported workflows, vulnerabilities, and destructive autofixes still warrant findings. Do not reopen accepted mitigations without new evidence. #### Prompt path resolution Resolve specialist scope files from the skill directory: `.apm/skills/skillsaw-review-panel/references/{specialist}.md`. Prefer that path over a bare `references/...` path — sub-agents may not share the skill's working directory. #### Parallel mode (default) Launch **all 7 specialist sub-agents in a single message** so they run concurrently, using the Agent tool with `run_in_background: false`. Do **not** use `run_in_background: true`: it can end a headless run before the verdict is posted. Wait for all results before Step 4, which handles errors. Each sub-agent gets: - The specialist role name and a one-line description of its lens - Instructions to read its scope file, at the path pattern above - The trusted patch path (`/tmp/skillsaw-panel-pr.diff`) in the automated workflow, or the merge base ref and local diff command otherwise - The PR number or branch name being reviewed - Any prior review findings (if detected in Step 2) - The findings format above, and the read-only contract - The proportional-review guidance above and instructions to read `REVIEW.md` Specialists have full read access; none sees another's output. Use `subagent_type: "general-purpose"`. Do NOT set the `model` parameter. If the Agent tool is not available (e.g. running in Codex or another client that lacks sub-agent support), fall back to serial mode automatically. #### Serial mode (`--serial`) Run all specialists inline in the main agent instead of dispatching sub-agents. Read [`references/serial-mode.md`](references/serial-mode.md) for the procedure — it is only needed on this non-default path. ### Step 4 — Completeness Gate Verify every specialist returned findings or "no issues" with what was checked. Retry errors or missing/malformed results **once**; never retry a valid empty result. If recovery fails, record the failure and post the verdict anyway, naming failed specialists. Never end the run here without a verdict. ### Step 5 — Run Panel Arbiter Synthesis After all specialists complete, review and synthesize directly: 1. Read all specialist findings. 2. **Deduplicate** — merge duplicates across specialists, keep strongest evidence. 3. **Filter noise** — remove false positives, style nitpicks, speculative findings, and issues already addressed in the branch. Apply proportional review to rare cases adequately handled by configuration. 4. **Resolve conflicts** — corroboration strengthens; when specialists disagree, weigh evidence, impact, available mitigations, and maintenance cost. Do not escalate solely because one reviewer imagines a rarer case. 5. Set a disposition (see below). 6. Include required actions (blocking) vs optional follow-ups. #### Disposition criteria **Follow these criteria:** - **APPROVE**: Set when no unresolved BLOCKING findings remain. - **REQUEST_CHANGES**: Set for BLOCKING findings that require code changes, but the change is in scope and fixable. - **NEEDS_DISCUSSION**: Set when findings need author input to resolve. The panel cannot decide without clarification — keep it here when the issue is neither a clean approve nor an outright change request or rejection. - **REJECT — REDIRECT TO PLUGIN**: Set when the Ecosystem Reviewer judged the change targets a low-adoption / unproven tool that does not belong in skillsaw core. Keep the change — it ships better as a rule plugin. Point the author to , the `skillsaw-create-plugin` skill, and `examples/plugins/skillsaw-example-plugin/`. - **REJECT**: Set when out of skillsaw's domain, wrong direction, or not viable, and not salvageable as a plugin. **Follow these arbiter biases:** - Prefer security over ergonomics. - Prefer repo consistency over local elegance. - Prefer existing patterns over novel ones. - Backward compatibility is paramount — breaking existing users is always blocking. - Keep core focused — prefer a plugin redirect over expanding core for niche tools. - CRITICAL: Reviews need to converge — endlessly re-litigating edge cases isn't productive. As each new panel round runs on the same PR, the bar for a new BLOCKING finding increases. Keep clean changes with no issues as a valid outcome — do not manufacture findings. ### Step 6 — Write and Post the Verdict Read `verdict-template.md` (same directory as this skill) and fill the placeholders with findings and synthesis. In the automated workflow, write the rendered verdict to exactly `/tmp/skillsaw-panel-verdict.md`. The trusted workflow step posts that file to the event's PR after the agent exits. Outside the automated workflow, if a PR number is known, post the rendered verdict as exactly ONE PR comment: ```bash gh pr comment --body "$(cat <<'VERDICT' VERDICT )" ``` If no PR number is known (local branch review), output the verdict directly to the user instead of posting a comment. ## Check the Quality Gates Verify a change passes when: - [ ] Architecture Reviewer: Verify structure and patterns are sound. - [ ] Python Expert: Ensure idiomatic, well-typed, performant Python. - [ ] Security & Supply Chain: Check no unmitigated vulnerability or supply chain risk. - [ ] QA Engineer: Verify adequate coverage of realistic failures and impactful edge cases. - [ ] Technical Writer: Ensure documentation consistent with changes. - [ ] Ecosystem Reviewer: Check target tool is in scope for core, or redirect to a plugin with links to skillsaw.org/plugins/. - [ ] Slopinator Reviewer: Check comments and docs describe shipped behavior, not the review history; check prose reads as human-written. - [ ] Panel Arbiter: Ratify trade-offs, set disposition.