self-review-loop

name	self-review-loop
description	Iteratively reviews a PR with fresh read-only reviewers, applies blocking feedback locally, verifies changes, and pushes one final squashed self-review commit only after a clean final review.
argument-hint	#N or N (PR number)
disable-model-invocation	false
allowed-tools	["Bash(git:*)","Bash(gh:*)","Bash(npm:*)","Bash(npx:*)","Bash(make:*)","Bash(pytest:*)","Bash(go:*)","Bash(cargo:*)","Bash(bundle:*)","Bash(dotnet:*)","Bash(mvn:*)","Bash(gradle:*)","Read","Write","Edit","Glob","Grep","Agent","Skill","AskUserQuestion","ToolSearch"]
mcpServers	["claude","codex"]

Self-Review Loop

Target PR: $ARGUMENTS. If absent, ask for a PR number.

Load references/github-pr-workflow.md for PR parsing, checkout, branch safety, and local diff rules. Load references/harness-adapters.md only when translating agent or skill invocation across harnesses.

Invariants

• Reviewers are fresh, read-only, and do not inherit prior review turns.
• The review target is local HEAD against origin/<baseRefName>, not the remote PR diff after local review commits exist.
• The loop succeeds only when the latest fresh review has no unresolved Critical/High findings after severity normalization.
• Max turns, oscillation, and final-review failures are blocked states.
• Per-turn commits stay local. Push only one final squashed self-review commit.
• Never force-push.

Setup

1. Resolve and checkout the PR using references/github-pr-workflow.md.
2. Confirm the PR is open.
3. Record:
   • review_base_sha=$(git rev-parse HEAD) immediately after checkout/pull
   • upstream branch
   • current branch
   • PR base and head refs
   • changed-file inventory from git diff --name-status origin/<baseRefName>...HEAD
4. Detect the verification command from project files or CI. If none exists, record no test suite detected.
5. Choose the review path:
   • prefer the local lean djenriquez-core:code-review skill when available
   • otherwise use direct fresh-review prompts that follow the same L0/L1/L2 staged policy from skills/code-review/SKILL.md
   • do not invoke nested review-team skills, including imported heavy team reviews, unless compatibility is proven and the user asked for that heavier path

Review Loop

Run at most 10 turns.

For each turn:

1. Spawn a fresh read-only reviewer or invoke the local lean code-review skill with no prior turn context.
2. Give the reviewer the repo path, PR number, base ref, and changed-file inventory.
3. For small diffs, the reviewer may inspect the full local diff. For large diffs, instruct it to inspect targeted paths with: git diff origin/<baseRefName>...HEAD -- <path>
4. Require findings grouped by Critical, High, Medium, and Low with file/line references and a verdict.
5. Normalize severity. Treat concrete correctness, security, data loss, broken error path, regression, or failing-test issues as blocking even if the reviewer labeled them lower.
6. If no blocking findings remain, leave the loop.
7. Triage every finding:
   • address real bugs, blocking risks, reasonable edge-case coverage, and codebase-backed convention issues
   • skip subjective, out-of-scope, false-positive, conflicting, or regression-risk findings with a recorded reason
8. Apply addressed changes.
9. If Go code is touched, load references/code-health-standards-go.md and apply it only to touched code as advisory guidance.
10. If this turn creates or moves package/module boundaries, run a structural pass using references/structure-standards.md and the Go addendum when relevant.
11. Run detected verification. If verification fails because of this turn, fix before continuing. If failure is pre-existing, record evidence and continue.
12. Commit this turn's self-review changes locally with a message that names the turn and summarizes addressed feedback.

If a review attempt times out, hits a transport error, returns null or invalid output, or disconnects mid-stream, retry that same review path once. If the retry also fails, fall back to a direct fresh read-only review when the failed path was a skill invocation; if direct review fails twice, stop as blocked and report the failure mode.

Detect oscillation after turn 2. If current changed files significantly overlap with files changed two turns earlier and reviewers are undoing prior fixes, stop as blocked.

Optional Cross-Model Debate

Do not load protocols/mcp-debate.md during setup. After a clean main-loop review, consider debate only when:

• the PR is high-risk or security-sensitive
• multiple review turns skipped disputed blocking feedback
• the final merge decision depends on a judgment call

Before any external-model call, ask one run/skip checkpoint. If approved, load protocols/mcp-debate.md and follow its discovery, model pinning, prompt-size, and failure handling rules.

If debate causes code changes, commit them locally and run one more fresh read-only review. If that final review has unresolved blocking findings, stop as blocked and do not push.

Squash And Push

Only publish when:

• the stop reason is a clean review
• required post-debate final review is clean
• the working tree is clean

Verify the range from review_base_sha..HEAD contains only commits created by this self-review run. If unrelated commits are present, stop and ask before rewriting local history.

Squash local self-review commits with a non-interactive soft reset, create one final commit, pull with rebase, rerun relevant verification if the commit changes or conflicts were resolved, then push normally.

Never use --force or --force-with-lease.

Final Summary

Report:

• PR number, branch, base, status, stop reason, and turn count
• review path used and why
• findings addressed and skipped, with reasons
• verification commands and results
• optional debate status
• final commit and push status, or blocked-state reason