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

textCopy code
/skillsaw-review-panel [--serial] [<pr number>]

Specialist Roster

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 <number> --json baseRefName and gh pr diff <number> 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:

bashCopy code
git diff <base-ref>...HEAD

Also run git diff <base-ref>...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:

bashCopy code
gh pr view <number> --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 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 https://skillsaw.org/plugins/, 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:

bashCopy code
gh pr comment <number> --body "$(cat <<'VERDICT'
<rendered 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.