pr-council-review

pr-council-review — PR Council Review skill

Council-driven PR review. Dispatches 6 baseline + N adaptive parallel reviewers, each scoped to one dimension, each invoking the relevant Claude Code specialized skill (e.g. security-review, code-review, verify), then synthesizes a single consensus verdict.

This skill is the canonical body. The Claude Code slash command at .claude/commands/gflow/pr-council-review.md is a thin wrapper that invokes this skill. Non-Claude tools (Antigravity / Codex / Cursor / Aider) can consume this SKILL.md directly via their own skill loaders.

Three modes:

1. No argument → list open PRs ranked by review priority; user picks. (See § 1.)
2. PR# argument → run the full council on that PR. (See § 2 onward.)
3. Branch mode → run the full council on the current local feature branch (no PR yet). Invoked via the /gflow:branch-review wrapper. See § 8 for the PR→branch translation table and pre-flight.

Treat YELLOW as soft block — it is advisory in name only; clear it or dismiss it with a logged justification (§ 5 step 8).

0 · Pre-flight

All six checks are mandatory. Any failure (except step 6, which records a finding) halts before Phase 1/2.

1. gh authenticated — run gh auth status. Non-zero exit → stop with: "gh is not authenticated. Run gh auth login and re-invoke."
2. Inside the repo — assert AGENTS.md AND CLAUDE.md exist in the working directory.
3. Resolve the argument:
   • Empty → jump to Phase 1 (Prioritize).
   • PR number → validate with gh pr view <N> --json number. If error → stop with the error verbatim.
4. Draft check (PR# mode only) — if gh pr view <N> --json isDraft returns true, surface a banner citing memory [[draft-pr-merge-trap]]: "PR #N is DRAFT. Reviewing is fine, but do NOT merge a draft (the merge API can close it + delete the head ref). Run gh pr ready N first if you intend to merge. Continue review? (yes/no)". Ask the user before dispatching.
5. Capture PR head ref + SHA (pin the review) — head_branch=$(gh pr view <N> --json headRefName --jq '.headRefName') and head_sha=$(gh pr view <N> --json headRefOid --jq '.headRefOid'). Pin both to a REVIEWED_SHA variable and pass to every dispatched agent so the council's verdict is anchored to one commit. The local working tree is NOT on the PR head; all file reads must go through git show $REVIEWED_SHA:<path> (or git show origin/$head_branch:<path> if you fetched first). If the author pushes new commits during the review, the council still reports against REVIEWED_SHA; the synthesizer notes any divergence in Phase 5 step 5.
6. Mechanical CI gate (D0 — non-LLM, runs BEFORE dispatch). The LLM dimensions reason about the diff; none of them run the repo's actual lint/format/link gates, so a whole-tree failure sails past the council (this happened on PR #269 — a latent ruff format failure in a file the diff only touched went green through 8 agents, then reddened CI and dragged SonarCloud new_coverage to 0). Run the exact CI gate commands (.github/workflows/ci.yml → Lint / Format check / Documentation links / Repo hygiene) against the reviewed tree:

   # Prefer running at REVIEWED_SHA. If HEAD is already there (reviewing your own
   # just-pushed PR, or branch-review mode), run in place:
   if [ "$(git rev-parse HEAD)" = "$REVIEWED_SHA" ]; then dir=.; else \
     dir=$(mktemp -d); git worktree add --detach "$dir" "$REVIEWED_SHA"; fi
   ( cd "$dir" && uv run ruff check src tests \
       && uv run ruff format --check src tests \
       && uv run python scripts/ci/check_doc_links.py \
       && uv run python scripts/ci/check_repo_hygiene.py )
   # if a worktree was created: git worktree remove --force "$dir" (Windows: prune later if locked)
   

   • Any non-zero → record a D0 — CI-mechanical RED. This is a hard blocker regardless of the LLM dimensions' verdicts; surface the failing command + output verbatim in the report and do NOT call the PR merge-ready. (Mirrors the SonarCloud-gate rule in the wrapper: the council must not bless a tree CI will reject.)
   • If running the gate is impractical (no uv, worktree add fails), fall back to gh pr checks <N> and inspect the test job's Lint/Format steps; if they are pending or failing, flag D0 as UNVERIFIED — must be confirmed green before merge, never as GREEN.
   • Unlike steps 1–5, a D0 failure does not halt — dispatch the LLM council anyway so its findings are gathered in one pass, then fold D0 into the Phase 5 verdict.