Shorten the self-review loop: tier round 1, drop forced minimum rounds

[vivek7405]

Problem

The self-review loop is still too long after #1159 (round shape, liveness) and #1173 (substantive gate, round budget). Every PR that enters the loop, whatever it touches, pays a fixed minimum of three sequential reviewer stages:

1. Round 1 is the deep-review workflow for EVERY task, which costs a scout + 6 fixed lenses + up to 6 dynamic lenses + an adversarial jury per finding (7 to 24 agents), even for a docs-only or skill-file PR.
2. A forced second round even when deep-review confirms nothing (the two-round minimum: "a deep-review that confirms nothing substantive is rare... run one delta-shaped pass anyway"). This adds a round to exactly the cheapest, cleanest case, and it second-guesses a result the juries already adversarially verified.
3. A mandatory standalone prose pass after convergence, one more fresh reviewer, even though every reviewer in the loop already reports and tags prose-tier findings (the tag is in the delta template and in deep-review's FINDINGS schema), so the dedicated pass mostly re-collects what the converging round already surfaced.

The owner's directive: make the review cycle shorter while keeping the quality bar where it matters. The quality asymmetry the loop itself already states is the lever: "a packages/*/src bug ships into every end-user app", while a docs/skill/website bug does not.

Design / approach

Keep deep-review's full adversarial depth for shipped source; stop paying it, and the two forced extra rounds, everywhere else. Four changes:

1. Tier round 1 by surface, file-checkable, never judgment-based (the same trick as the docs: two-tier review-loop exit, substantive gate then one prose pass #1171 substantive gate: surface membership is checkable from the diff, so the agent motivated to go light cannot misjudge it). If the PR's diff touches shipped source, defined as packages/*/src/**, packages/cli/lib/**, or packages/cli/templates/**, round 1 is the deep-review workflow, unchanged. Otherwise (docs site, website, blog, skills, hooks, tests-only, examples, scaffold docs) round 1 is one broad fresh reviewer: the existing delta-verifier template with the full diff as its question. A light-tier PR's loop is then typically one reviewer, or a handful when it finds things. The user asking for a deep review always forces the deep tier.
2. Drop the forced second round after a clean deep-review. A deep-review run that confirms nothing substantive ends the substantive loop by itself: its findings were already jury-refuted, which is exactly the adversarial re-check the extra delta round was standing in for. Delta rounds still run after every round that DOES produce substantive fixes, until one finds nothing substantive. The two-round minimum is replaced by: minimum one round; fixes always get a fresh delta round.
3. Fold the prose pass into the converging round. The round that finds nothing substantive (or whose findings are all prose once tags are verified) IS the prose sweep: its prose-tier findings are applied without re-review (already the gate's rule) and the loop ends. The standalone mandatory prose-pass reviewer is removed. The gate's one exception stays: a prose fix that touches a substantive surface gets one delta-scoped check of that fix alone. The third-party-internals content rule stays.
4. Trim deep-review defaults, since it now runs only where its depth is earned: dynamic lens cap 6 to 3 (the scout's "zero is a fine answer" plus measured runs rarely earning six), default maxAgents 24 to 16 (still clamped 8 to 60, still overridable per run).

Everything else is untouched: liveness/watchdog rules, worktree safety, the posting mechanics (one review object per round), the refuter gate on expensive delta findings, the substantive gate and its asymmetric tag verification, the 5-round budget, BLOCKED/OVER BUDGET exits, the deferral ledger, the deferred-suites + CI read after convergence, and the when-to-skip rule.

Implementation notes (for the implementing agent)

• Where to edit:
  • .claude/skills/webjs-start-work/SKILL.md ### How the loop works (L311-L385): the round-1 bullet (L324) gains the surface tier; the two-round-minimum paragraph (L381) is replaced; step 4 (L379) loses the standalone prose pass and instead ends the loop on the converging round with its prose findings applied without re-review (keep the deferred-suites/CI parallel-run text, which lives in the same step); the last-round absolute (L383), the standalone-review entry (L385, "ALWAYS starts with a fresh deep-review run" becomes tier-respecting), ### Reporting after the loop (L391-L403, the report template says "plus the prose pass" and the <K> counting rules mention it), and the two cross-references at L105 and L111 ("a round finding nothing substantive, then the prose pass").
  • .claude/workflows/deep-review.js: maxAgents default at L34 (24 to 16), the dynamic-lens caps at L110 (maxItems: 6), L127/L141 (slice(0, 6)), and the scout prompt's "ZERO to six" wording at L134; meta.whenToUse (L4) says "The round-1 review for any PR entering a review loop", which becomes shipped-source-tier only.
  • .claude/hooks/route-skills.sh L190: the code-review directive hard-codes "round 1 is the deep-review workflow" and "one bounded prose pass ends it"; update in lockstep (the comment at L182 says exactly this).
• Landmines / gotchas:
  • Two byte-identical copies of the skill exist: in-repo and ~/.claude/skills/webjs-start-work/SKILL.md. Every docs: make the self-review loop fast, parallel, and stall-proof #1159/docs: exit the review loop on a substantive gate plus one prose pass #1173 PR verified them with diff -q after the change; do the same, copying in-repo onto ~/.claude.
  • docs: make the self-review loop fast, parallel, and stall-proof #1159 explicitly justified the uniform deep-review rule ("a uniform rule cannot be misjudged the way a by-risk bifurcation can"). This issue supersedes that at the owner's direction; the tier must stay SURFACE-based (paths in the diff) precisely so the misjudgment concern stays closed. Do not write an importance-based tier.
  • The loop's cross-references are by name, not ordinal (docs: make the self-review loop fast, parallel, and stall-proof #1159 did this deliberately); when removing the prose pass, sweep EVERY mention (grep -n "prose pass" SKILL.md finds them all) or a dangling reference ships.
  • test/hooks/route-skills.test.mjs asserts routing behavior, not loop wording, but run it anyway (16/16) since the hook file is edited.
  • node --check is inapplicable to deep-review.js (top-level return is legal only in the Workflow runtime's async context, per docs: exit the review loop on a substantive gate plus one prose pass #1173's test plan); validate by wrapping as an async function body.
• Invariants to respect: AGENTS.md invariant 11 (prose punctuation, WebJs casing) applies to all edited prose; the gate changes only WHEN the loop exits, never WHETHER a surface is reviewed (both tiers still posted and resolved on the PR); the deferred suites still run in full after convergence.
• Tests + docs surfaces: node --test test/hooks/route-skills.test.mjs; no packages/*/src change, so no docs-site/website/scaffold surface (same N/A rationale as docs: make the self-review loop fast, parallel, and stall-proof #1159/docs: exit the review loop on a substantive gate plus one prose pass #1173).

Acceptance criteria

• Round 1 is deep-review only when the PR diff touches packages/*/src/**, packages/cli/lib/**, or packages/cli/templates/**; otherwise one broad fresh reviewer, with an explicit user ask always forcing the deep tier.
• A round 1 (either tier) that finds nothing substantive ends the substantive loop with no forced second round; a round with substantive fixes still gets a fresh delta round on the new HEAD.
• The standalone prose pass is gone; the converging round's prose-tier findings are applied without re-review, and the prose-fix-touching-substantive-surface exception survives.
• deep-review.js defaults: maxAgents 16, dynamic lenses capped at 3, whenToUse reflects the tier.
• The route-skills.sh code-review directive matches the new loop wording; node --test test/hooks/route-skills.test.mjs passes 16/16.
• grep -n "prose pass" .claude/skills/webjs-start-work/SKILL.md shows no stale reference to the removed standalone pass.
• Both skill copies byte-identical (diff -q) after the change.
• Liveness, worktree-safety, posting, refuter-gate, budget, and deferral rules are textually untouched except where they cross-referenced the prose pass or two-round minimum.