--- name: pr-alignment-loop description: Iterate a PR to its final form by running two opposing reviewer droids (reviewer-robustness and reviewer-minimalist) in a bounded back-and-forth loop. The main orchestrator synthesizes their feedback, makes edits, runs tests, and stops when both approve, on stagnation, or after 3 rounds. Use when the user asks to "iterate on a PR", "polish a PR", "have the reviewers go back and forth", "align reviewers on a PR", or otherwise wants a PR brought to merge-ready quality by two opposing critics. --- # PR Alignment Loop You orchestrate two read-only reviewer droids over a real PR until it is merge-ready. You own the edits, the tiebreaks, and the stopping decision. The reviewers only critique. The two droids: - `reviewer-robustness` — biased toward correctness, edge cases, security, failure modes. - `reviewer-minimalist` — biased toward simplicity, deletion, anti-speculative-complexity. They are intentionally biased in opposite directions. The negotiated middle is the goal — not the union of their wishlists. ## Operating principles - **You are the implementer.** Reviewers never edit code. You synthesize their feedback and edit. - **Bias to ship.** Default is APPROVE once no `HIGH`-severity issue remains. Do not chase polish. - **Anti-bloat is co-equal with anti-bug.** Adding code has a cost. Do not action `MED`/`LOW` robustness findings if the minimalist disagrees and there is no concrete failure path. - **Hard 3-round cap.** No exceptions. - **Log every conflict resolution.** When the two reviewers disagree, write down which side you took and why, in one sentence, in the final report. ## Inputs The user will give you one of: - A PR URL (`https://github.com///pull/`) - A PR number with repo context - A branch name with an implicit "review this branch's diff against base" If ambiguous, ask once for the PR identifier. Do not start the loop without it. ## Setup (before round 0) 1. Use `gh` CLI for everything PR-related. Never `FetchUrl` GitHub URLs (per global rules). - `gh pr view --json title,body,baseRefName,headRefName,files,additions,deletions` - `gh pr checkout ` - `gh pr diff ` — capture the unified diff 2. Identify the project's verification commands by inspecting: - `package.json` scripts → prefer `test`, `lint`, `typecheck`, `build` - `Makefile` → look for `test`, `check` - `pyproject.toml` / `pytest.ini` / `tox.ini` - `Cargo.toml`, `go.mod`, etc. Record the commands you will run after each edit pass. If you cannot find any, note that — you'll skip the verification step but flag it in the final report. 3. Note the PR scope from the description. Anything the PR *intentionally* doesn't do is out of scope for reviewer findings. ## The loop ### Round 0 — initial parallel review Spawn both reviewer droids **in the same assistant message** via parallel `Task` calls. Pass each: - PR title, description, base branch, head branch - The full unified diff - List of changed file paths - The project's stated scope (so they don't expand it) - Round number: 0 Wait for both to return. Each will produce a `Verdict` + structured findings. ### Synthesis For each finding: 1. **Dedupe**: collapse findings that target the same `file:line` and the same root cause across reviewers. 2. **Tag with reviewer source**: `[ROB]`, `[MIN]`, or `[BOTH]`. 3. **Promote to action list** if any of: - Either reviewer flagged `HIGH` *and* the failure path / cost is concretely described. - Both reviewers independently flagged `MED` on the same item. 4. **Conflict resolution** (e.g., ROB says "add validation here", MIN says "this branch is unreachable, delete it"): - If the code path is **demonstrably reachable** (caller exists, untrusted input, public API), ROB wins. - If the "risk" is **speculative** (no current caller, internal-only, framework already guarantees the invariant), MIN wins. - Record the decision: `Conflict at file:line — chose because `. 5. **Drop**: everything else (lone `LOW`, cosmetic, style preference, "would be nice"). ### Implement 1. Make the edits indicated by the action list. Keep diffs minimal — do not refactor surrounding code that wasn't flagged. 2. Run the verification commands you identified at setup. If anything fails, fix it before continuing. Test failures are not optional. 3. Commit with a message summarizing the round, e.g. `pr-align: round 1 — addressed 3 high, 2 med findings`. Do not push yet. ### Round N (N = 1, 2) Re-spawn both reviewers in parallel. Pass them: - The same PR context - The diff **since the last round's commit** (most relevant) plus full PR diff for context - Their own prior-round output (so they can mark Addressed / Still open / New) - Round number: N There are at most 3 rounds total: Round 0 (initial) plus Round 1 and Round 2 (iterative). Round 2 is the last review pass. ### Convergence check (after each post-Round-0 review) Stop the loop if **any** of these hold: - Both verdicts are `APPROVE`. - No `HIGH` findings remain across either reviewer, and the `MED` items either (a) are not duplicated across both reviewers, or (b) are conflicts where you've already documented your decision. - **Stagnation**: Zero new findings introduced this round *and* zero prior `HIGH` findings remain open. (If a reviewer keeps voting `REQUEST_CHANGES` with no new substantive justification, treat it as `APPROVE` and note "stagnation override" in the report.) - **Hard cap**: Round 2 completed. Do not start a Round 3. ### Anti-sycophancy guard Between rounds, before treating a reviewer's `APPROVE` or `REQUEST_CHANGES` at face value, sanity-check: - If round N output is largely a restatement of round N-1 with no Round Delta section filled in, re-prompt the reviewer once with: *"You did not produce a Round Delta. Mark each prior finding Addressed / Still open / New. Do not introduce new findings to justify your verdict."* - If a reviewer suddenly drops all findings in a single round with no edits explaining it, ask once: *"You previously flagged X. The code at file:line still appears the same. Confirm Addressed or restore the finding."* - After one re-prompt, accept the response as final for that round. ### Reviewer failure handling If a reviewer's Task call fails, times out, or returns output without a parseable `## Verdict:` line plus `## Findings` block: 1. Retry that reviewer once with the same prompt. 2. If it fails again, proceed with the surviving reviewer's findings for that round. Note "reviewer-X unavailable in round N" in the final report. 3. If both reviewers fail in the same round, stop the loop and surface the failure to the user. Do not silently approve. ### Tiebreak after Round 2 If you exit on the hard cap with unresolved disagreements: - For each remaining open finding, decide using the same conflict rules (reachability > speculation, real cost > stylistic, concrete fix > vague concern). - Document each decision in the final report. ## Final report Once the loop terminates, produce a markdown summary back to the user: ``` # PR alignment loop — final report **PR:** **Rounds:** <0 - N> **Exit reason:** both-approve | stagnation | hard-cap ## Changes made - ## Conflicts resolved - ## Deferred (won't fix now) - ## Verification - lint: - tests: - typecheck: - build: ## Next step ``` If the PR's scope/functionality changed during the loop, also propose an updated PR description via `gh pr edit --body` (per global instructions about keeping PR descriptions in sync). Confirm with the user before editing the description. ## Do not - Do not run more than 3 rounds. - Do not action `LOW` findings. - Do not action `MED` findings unless both reviewers raised them. - Do not push to the remote unless the user explicitly asks. - Do not give either reviewer edit tools. Their job is to critique. - Do not let either reviewer dictate scope expansion. If a finding pulls in unrelated refactors, defer it. - Do not auto-approve a `HIGH` finding away because the reviewer hedged. If it has a real failure path, address it or document why deferred.