Design notes

Why pr-reviewer works the way it does. Read this when changing the skill, not when running a review.

• Why pin SHAs instead of cloning the head branch? Version 1 cloned --branch <head> and refreshed with reset --hard, so a push between rounds silently changed what round 3 reviewed, and the convergence check compared two different trees. Pinning head, base and merge-base, and verifying them in every pass, is what makes "converged" mean something.
• Why three reviewers and an assessor rather than one reviewer who re-checks? Re-checking your own work is biased toward confirming it. Independent lenses that never see each other find different things; the assessor's steel-man then has to argue against claims it did not make. Single mode keeps the steel-man but loses the independence, which is why it is the fallback and the report says so.
• Why does the assessor do the steel-man instead of a separate "challenger"? Merging and challenging are the same act: to decide whether two reviewers found the same defect you have to decide what the defect really is. Splitting them would double the reads for no extra independence.
• Why a separate summary agent? The assessor's output is evidence; the report is prose for the author. Keeping them apart stops the report drifting from the findings, and the summary agent runs on the cheapest tier.
• Why is the PR's text data, not instructions, and why no test runs? Everything in a PR is author-controlled. A reviewer with a shell that follows "run this to verify" from a PR body has executed the author's code with the user's credentials. Static reading plus read-only git is the whole budget unless the user opts in.
• Why a refresh budget that resets when a review finishes? Without a budget, an author pushing every few minutes makes an unfinished review restart forever; a per-invocation budget would reset on every /loop tick and protect nothing; a budget that never reset would refuse the third ordinary re-review in a PR's life. Counting only restarts of an unfinished review is the one scope that matches the problem.
• Why a state file? Without one every round starts from scratch and the review never compounds. The revision header is what lets the file hold the history of a moving PR without ever mixing revisions.
• Why never start the loop? Looping is a runtime capability, not a review capability. The skill reports whether another round is warranted; the runtime or the user iterates.
• Why a clone instead of git checkout or git worktree, and never into the cwd or the repo? Switching the user's branch is a surprising side effect. A shallow clone in the skill's own cache keeps the user's directory untouched, cannot inherit the PR's project files, and cleans up with rm -rf.
• Why does the report never mention posting? The report is the artifact. Posting is a separate question, asked after the artifact is printed, with its own revalidation.
• Lineage. The staged structure, pinned revision, freshness record, validation-and-limits section and guided publication borrow from a staged-review workflow by kiview; the steel-man, the convergence loop and the portability are version 1's.