pr-critic-loop

name	pr-critic-loop
description	Review the current repository pull request as a harsh critic, fix every actionable finding, verify the fixes, and repeat the critic/fix loop until no actionable findings remain. Use when the user asks to review, criticize, harden, or autopilot a PR or current branch, especially in Swift repos that must follow repo AGENTS files and a shared canonical rule set.

PR Critic Loop

Follow the shared conventions in ../conventions.md.

Overview

Run a closed-loop PR review: load rules, inspect the active PR, produce concrete findings, fix them, verify them, then review again. Treat the critic as adversarial and first-principles driven, but keep the implementation pragmatic and tightly scoped.

Workflow

1. Establish the review target.

   • Work from the current repository unless the user names another path.
   • Prefer gh pr view --json number,url,headRefName,baseRefName,state,mergeable,statusCheckRollup to identify the active PR.
   • If no PR exists, review the current branch against its upstream or against main.
   • Run git status --short --branch before editing. Do not discard user changes.

2. Load rules before reviewing.

   • Read repository-local AGENTS.md files that apply to the repo and touched paths.
   • Read the shared Swift rule index when it exists, then load the canonical rule files it names. For Swift work, at minimum read general.md, repo-structure.md, gof-di-rules.md, code-style.md, namespacing.md, testing.md, verification-before-completion.md, github-discipline.md, and testing-discipline.md when those files exist.
   • Also load concurrency.md when Sendable, async, actors, tasks, or mutable shared state are touched, and cross-platform.md when Linux support, platform APIs, package manifests, or Foundation compatibility are touched.
   • If the repo points at a local Rules/ folder instead, load that folder's CONVENTIONS.md plus the matching topic files.
   • If the shared rule set is missing, search for it locally. If unavailable, continue with repo rules and report that gap.
   • After the rules are loaded, include the confirmation phrase rules-loaded once in the working notes or PR comment.

3. Critic pass. (See conventions.md § The critic / fix loop for the underlying mechanic.)

   • Do not silently fix first. Produce critic remarks before each fix pass unless the user explicitly asks for a private/internal pass.
   • Start with findings, ordered by severity.
   • Be harsh about correctness, regressions, public API shape, cross-platform behavior, data loss, security, invalid assumptions, flaky tests, missing tests, rule violations, and user-visible quality.
   • Tie every finding to an exact file and line when possible.
   • Explain why the behavior fails from first principles. Include a minimal reproduction or command when practical.
   • Do not list style preferences unless they violate loaded rules or create real maintenance cost.
   • If no actionable findings exist, say that plainly and stop the loop.

4. Fix pass.

   • Make a short checklist from the critic findings.
   • Fix all actionable findings without waiting for confirmation unless the fix requires destructive git operations, credentials, paid/external services, or a product decision the repo cannot answer.
   • Keep edits scoped to the finding. Avoid unrelated refactors.
   • Add or update tests for any behavior change or bug fix.
   • Update docs, changelog, PR body, or issue links when required by loaded rules.
   • Use repo tooling and established patterns. In Swift packages, prefer Swift Testing and package-local commands.

5. Verify pass.

   • Run the narrow test that proves each fix.
   • Run the repo's required format, lint, build, and test commands before claiming the PR is clean.
   • For Swift repos, prefer the repo's own scripts first, then swiftformat, swiftlint, swift build, and swift test as applicable.
   • If the PR is pushed, check GitHub CI with gh pr checks.

6. Repeat.

   • Run a fresh critic pass against the updated diff and PR state.
   • Ignore resolved findings unless the fix regressed them.
   • Continue critic -> fix -> verify until the critic has no actionable findings.
   • If the same blocker repeats for three consecutive loop passes and progress is impossible without user input or external state, stop and report the blocker.

Critic Standards

• Treat tests as part of the product. A behavioral fix without a relevant test is usually incomplete.
• Treat Linux compatibility as a release requirement when the package claims Linux support.
• Treat public API changes as compatibility decisions. Check call sites, docs, and generated examples.
• Treat docs as executable promises. If docs say a feature works, look for tests or implementation evidence.
• Prefer reproducible claims over visual impressions. Use generated artifacts, text extraction, snapshots, parsers, or command output when possible.
• Avoid vague remarks. Every critic remark should imply a concrete fix or a clear reason to reject it.

GitHub Handling

• If a PR exists and the user asked for autopilot, push fixes to the PR branch when local verification passes.
• Add concise PR comments after meaningful loops: critic pass number, findings fixed, verification commands, CI state.
• Close issues only when the PR or pushed branch actually addresses them and verification has passed.
• Do not merge unless the user explicitly asks.

Output Shape

During work, keep updates short and concrete. When reporting a critic pass, use:

Critic pass N:
1. Severity - file:line - finding
   Why:
   Fix:

When complete, report:

• final critic result
• changed files summary
• verification commands and pass/fail counts
• PR URL and CI state when applicable
• any residual risks or intentionally deferred findings