skillsaw-review-panel

name	skillsaw-review-panel
description	Serial multi-specialist code review panel for skillsaw PRs. Runs 6 specialist reviewers (Architecture, Python Expert, Security & Supply Chain, QA Engineer, Technical Writer, Ecosystem) inline then synthesizes a single verdict.
compatibility	Requires git, gh CLI, and internet access
license	Apache-2.0
user-invocable	true
metadata	{"author":"stbenjam","version":"2.0"}

Review Panel — Serial Multi-Specialist Review

Run 6 specialist reviewers + 1 arbiter inline in the main agent, one after another. Keep the review serial by design — derive the repo context once and share it across all specialists to keep token cost low. Each specialist can read prior specialists' file reads (though not their findings).

Read each specialist's detailed scope from the references/ directory alongside this skill; load it only when that specialist runs (progressive disclosure) — keep this file lean and pull the scope in on demand.

Keep the panel advisory. It does not gate merge. It surfaces findings; the maintainer and PR author review and decide ship.

Specialist Roster

Specialist	Lens	Scope
Architecture Reviewer	Check module boundaries, abstraction level, SOLID, cross-file impact, error propagation	references/architecture.md
Python Expert	Review idiomatic Python, type hints, performance, stdlib usage, packaging conventions	references/python-expert.md
Security & Supply Chain Reviewer	Check injection, credential handling, dependency trust, lockfile integrity, build pipeline	references/security-supply-chain.md
QA Engineer	Test coverage gaps, untested error paths, edge cases, concrete test suggestions	references/qa-engineer.md
Technical Writer	Verify documentation accuracy, completeness, consistency with code changes, CLAUDE.md drift	references/technical-writer.md
Ecosystem Reviewer	Review target-tool adoption in the current LLM landscape; core-vs-plugin scope boundary	references/ecosystem.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 — Determine Base Ref and Read the Diff

Check what the changes are being compared against:

• If a PR number is provided: use gh pr view <number> --json baseRefName to get the base branch, then compute the merge base.
• If no PR number: 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.

Check out the PR branch if not already on it:

gh pr checkout <number>

Read the diff once:

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

When reviewing a PR, check for previous panel review comments:

gh pr view <number> --json comments --jq '.comments[] | select(.body | contains("Generated by skillsaw-review-panel")) | {createdAt, body}'

If prior reviews exist, note which findings have been addressed by subsequent commits and which remain unresolved. Avoid re-raising resolved issues.

Step 3 — Run Specialists Serially

Run each specialist in roster order (Architecture, Python Expert, Security & Supply Chain, QA Engineer, Technical Writer, Ecosystem):

1. Write the specialist name as a heading.
2. Read that specialist's references/*.md file now (in the references/ directory alongside this skill) — read the detailed scope it holds. Do not review from the one-line lens alone.
3. Review the diff and repo through that specialist's lens. Read files, grep, and run git commands to gather the evidence the scope calls for — context from earlier specialists' file reads carries over.
4. Write findings in this format:
   • Severity: set BLOCKING | SUGGESTION | NOTE
   • File:line — include the reference when applicable
   • Finding — write a description
   • Recommended action — make it explicit
5. If no issues found, say so and review what you checked.
6. Move on to the next specialist.

Follow this severity calibration:

• BLOCKING: Set for correctness regressions, security vulnerabilities, architectural faults that compound, or (for the Ecosystem Reviewer) a scope violation that warrants redirect-to-plugin. Always include explicit rationale for why this blocks.
• SUGGESTION: Set for substantive feedback that improves the code but is not a correctness issue. Keep this the default for real feedback.
• NOTE: Set for one-line polish, style nits, minor improvements.

Step 4 — Run Panel Arbiter Synthesis

After all specialists complete, review and synthesize directly:

1. Read all specialist findings.
2. Review and resolve any conflicts between specialists.
3. Set a disposition (see below).
4. Include required actions (blocking) vs optional follow-ups.

Follow these disposition 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.

Keep clean changes with no issues as a valid outcome — do not manufacture findings.

Step 5 — Write and Post the Verdict

Read verdict-template.md (same directory as this skill) and fill the placeholders with findings and synthesis. Write the rendered verdict as exactly ONE PR comment:

gh pr comment <number> --body "$(cat <<'VERDICT'
<rendered verdict>
VERDICT
)"

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 test coverage, edge cases addressed.
• 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/.
• Panel Arbiter: Ratify trade-offs, set disposition.