pr-review: add depth-floor mandates to prevent rubber-stamp approvals
Context
#10154 filed 2026-04-21 (epic-review skill) produced PR #10155. Gemini 3.1 Pro (Antigravity harness) reviewed and approved. Structurally, the review was fully skill-compliant: all seven [EVALUATION_METRICS] scored with justifications, all three graph-ingestion tags ([KB_GAP], [TOOLING_GAP], [RETROSPECTIVE]) present, cross-linking to ticket + related graph nodes, template structure followed, peer-review opening, session ID footer.
Empirically, the review was rubber-stamp-shaped despite satisfying every skill mandate. The gap is in the skill, not the reviewer.
The Problem
Four specific skill gaps surfaced by reviewing the review:
[COMPLEXITY] scored 85 with no justification for the 15-point deduction. Text read: "Deftly handles the complex staging logic by strictly enforcing that Stages 1-2 gate Stages 3-5." That describes what the PR does, not what's complex about it. The skill mandates a brief justification per metric but doesn't require deduction-specific reasoning — so any sub-100 score becomes cosmetic.
Required Actions section used - [x] All checks pass and no required changes identified. as a pre-ticked placeholder. Template reads "To proceed with merging, please address the following: - [ ] Item 1". The null-state ("no items") has no documented semantics — Gemini invented a workaround that reads as box-checking rather than genuine review.
Zero adversarial observations despite a real latent gap. The PR introduced a new epic-review skill with a "runs before ticket-intake" integration claim, but did NOT update ticket-intake to actually check for epic-review state. Without that update, the integration claim is aspirational. Author missed it; reviewer didn't catch it. The skill doesn't mandate any minimum adversarial observation, so an entirely affirming review passes.
No cross-skill integration audit. For PRs that introduce new workflow primitives or conventions, reviewer should verify whether other skills need updating to reference the new pattern. pr-review doesn't mandate this; the integration gap in #10155 shipped silently as a result.
This matches the cross-model asymmetry documented in .agent/skills/epic-review/references/epic-review-workflow.md §8 ("Gemini-family reviewers tend toward quick-win framing"). epic-review addresses the asymmetry via mandatory stop-condition alternatives when stages fail. pr-review has no analogous depth floor — approval-by-default is structurally permitted.
Combined effect: reviewers whose failure mode tilts toward quick-win can satisfy the skill with reviews that don't adversarially examine the code. Reviewers whose failure mode tilts toward over-rigor (Claude-family) will go deeper regardless — the skill floor is invisible to them. The floor matters only for the quick-win failure mode, which is where the current skill leaves the rigor gap.
The Architectural Reality
.agent/skills/pr-review/SKILL.md — Progressive Disclosure router (1 line body + frontmatter).agent/skills/pr-review/references/pr-review-guide.md — authoritative payload, 6 sections: Core Philosophy, Agent Operational Mandates, Structural Evaluation Metrics, Graph Ingestion Tags, Required Actions & Cross-Linking, Review Template.agent/skills/pr-review/assets/pr-review-template.md — structural skeleton used by reviewers
Empirical artifact: PR #10155, Gemini review (relay comment on 2026-04-21T12:03:01Z).
The Fix
Four additive enhancements to pr-review-guide.md + one template adjustment:
1. Score-Deduction Justification (§3 metrics)
Add explicit requirement: any metric scored below 100 MUST include a specific reason for the deduction. Restated praise is NOT a justification. Acceptable form: "15 points deducted because stage-gating introduces reasoning complexity an author unfamiliar with the pattern will need to internalize." Unacceptable form: "Deftly handles the complex staging logic" (describes what, not what's deducted).
2. New §7 "Depth Floor" — Minimum-One-Challenge Mandate
Peer-reviews MUST name at least one: weakness, unverified assumption, edge case, or follow-up concern. If none exists, reviewer MUST explicitly document the search: "I actively looked for [X], [Y], [Z] and found no concerns." This makes the search visible and prevents approval-by-default. Self-reviews already have an analogous requirement via §1's "actively hunt for blind spots" language; this extends the discipline to peer-reviews.
3. Required-Actions Semantics for Zero-Issue PRs (§5 + template)
For PRs with no required actions, replace the checkbox list with a single explicit sentence: "No required actions — ready to merge." Do NOT pre-tick placeholder items. Template (assets/pr-review-template.md) updated to show both forms (checkbox list for PRs with actions; single sentence for zero-issue PRs).
4. New §8 "Cross-Skill Integration Audit"
For PRs that introduce new workflow primitives, skill files, architectural conventions, or MCP tool surfaces, reviewer MUST verify whether other skills / docs / tools need updating to reference the new pattern. Specific checks:
- Does any existing skill document a predecessor step that should now fire this new pattern?
- Does
AGENTS_STARTUP.md §9 (Workflow skills) need updating?
- Does any reference file mention the predecessor pattern and need to mention the new one?
The §8 check would have caught #10155's ticket-intake gap.
Acceptance Criteria
Out of Scope
- Mechanical enforcement (review-linter, score-deduction checker) — discipline via skill doc, consistent with
ticket-intake / pull-request / epic-review pattern
- Retroactive re-review of existing merged PRs — enhancement applies to future reviews
- Cross-model review coordination / deduplication — separate concern
- Changes to
[EVALUATION_METRICS] category list itself — current categories are fine; the gap is in how they're used
- Fix for #10155's specific ticket-intake integration gap — separate follow-up ticket if needed; this ticket is about the skill, not any individual shipped PR
Avoided Traps
- Mechanical rigor enforcement (score linter, minimum-word-count). Rejected. Discipline via skill doc is lower-friction and consistent with all other workflow skills. A reviewer who wants to rubber-stamp can always find a way; the skill's job is to make rigor the default path, not eliminate low-effort paths mechanically.
- Forcing fabricated adversarial observations when PRs are genuinely clean. Rejected as over-correction. The "documented search" fallback ("I looked for X/Y/Z and found nothing") lets reviewers be honest about no-issue findings without manufacturing fake concerns. Auditable, not adversarial-for-its-own-sake.
- Calibrating Claude toward Gemini's style (or vice versa). Rejected. Cross-model asymmetry is the feature. Skill enhancements set a floor both models must meet; they don't push either model toward the other's style.
Related
- #10154, #10155 (epic-review skill + PR — empirical artifact that surfaced these gaps)
.agent/skills/epic-review/references/epic-review-workflow.md §8 — cross-model asymmetry framing that predicted the rubber-stamp outcome.agent/skills/pr-review/ — files to be modified- Discussion #10137 (MX paradigm — another MX-workflow refinement loop, now on the review substrate itself)
- Upstream session heritage:
71dc3cd8-d39d-48e1-ac62-e240ca67d1a5 (this session's workflow planning arc)
Origin Session ID: 71dc3cd8-d39d-48e1-ac62-e240ca67d1a5
pr-review: add depth-floor mandates to prevent rubber-stamp approvals
Context
#10154 filed 2026-04-21 (epic-review skill) produced PR #10155. Gemini 3.1 Pro (Antigravity harness) reviewed and approved. Structurally, the review was fully skill-compliant: all seven
[EVALUATION_METRICS]scored with justifications, all three graph-ingestion tags ([KB_GAP],[TOOLING_GAP],[RETROSPECTIVE]) present, cross-linking to ticket + related graph nodes, template structure followed, peer-review opening, session ID footer.Empirically, the review was rubber-stamp-shaped despite satisfying every skill mandate. The gap is in the skill, not the reviewer.
The Problem
Four specific skill gaps surfaced by reviewing the review:
[COMPLEXITY]scored 85 with no justification for the 15-point deduction. Text read: "Deftly handles the complex staging logic by strictly enforcing that Stages 1-2 gate Stages 3-5." That describes what the PR does, not what's complex about it. The skill mandates a brief justification per metric but doesn't require deduction-specific reasoning — so any sub-100 score becomes cosmetic.Required Actions section used
- [x] All checks pass and no required changes identified.as a pre-ticked placeholder. Template reads "To proceed with merging, please address the following: - [ ] Item 1". The null-state ("no items") has no documented semantics — Gemini invented a workaround that reads as box-checking rather than genuine review.Zero adversarial observations despite a real latent gap. The PR introduced a new
epic-reviewskill with a "runs before ticket-intake" integration claim, but did NOT updateticket-intaketo actually check for epic-review state. Without that update, the integration claim is aspirational. Author missed it; reviewer didn't catch it. The skill doesn't mandate any minimum adversarial observation, so an entirely affirming review passes.No cross-skill integration audit. For PRs that introduce new workflow primitives or conventions, reviewer should verify whether other skills need updating to reference the new pattern.
pr-reviewdoesn't mandate this; the integration gap in #10155 shipped silently as a result.This matches the cross-model asymmetry documented in
.agent/skills/epic-review/references/epic-review-workflow.md§8 ("Gemini-family reviewers tend toward quick-win framing").epic-reviewaddresses the asymmetry via mandatory stop-condition alternatives when stages fail.pr-reviewhas no analogous depth floor — approval-by-default is structurally permitted.Combined effect: reviewers whose failure mode tilts toward quick-win can satisfy the skill with reviews that don't adversarially examine the code. Reviewers whose failure mode tilts toward over-rigor (Claude-family) will go deeper regardless — the skill floor is invisible to them. The floor matters only for the quick-win failure mode, which is where the current skill leaves the rigor gap.
The Architectural Reality
.agent/skills/pr-review/SKILL.md— Progressive Disclosure router (1 line body + frontmatter).agent/skills/pr-review/references/pr-review-guide.md— authoritative payload, 6 sections: Core Philosophy, Agent Operational Mandates, Structural Evaluation Metrics, Graph Ingestion Tags, Required Actions & Cross-Linking, Review Template.agent/skills/pr-review/assets/pr-review-template.md— structural skeleton used by reviewersEmpirical artifact: PR #10155, Gemini review (relay comment on 2026-04-21T12:03:01Z).
The Fix
Four additive enhancements to
pr-review-guide.md+ one template adjustment:1. Score-Deduction Justification (§3 metrics) Add explicit requirement: any metric scored below 100 MUST include a specific reason for the deduction. Restated praise is NOT a justification. Acceptable form: "15 points deducted because stage-gating introduces reasoning complexity an author unfamiliar with the pattern will need to internalize." Unacceptable form: "Deftly handles the complex staging logic" (describes what, not what's deducted).
2. New §7 "Depth Floor" — Minimum-One-Challenge Mandate Peer-reviews MUST name at least one: weakness, unverified assumption, edge case, or follow-up concern. If none exists, reviewer MUST explicitly document the search: "I actively looked for [X], [Y], [Z] and found no concerns." This makes the search visible and prevents approval-by-default. Self-reviews already have an analogous requirement via §1's "actively hunt for blind spots" language; this extends the discipline to peer-reviews.
3. Required-Actions Semantics for Zero-Issue PRs (§5 + template) For PRs with no required actions, replace the checkbox list with a single explicit sentence: "No required actions — ready to merge." Do NOT pre-tick placeholder items. Template (
assets/pr-review-template.md) updated to show both forms (checkbox list for PRs with actions; single sentence for zero-issue PRs).4. New §8 "Cross-Skill Integration Audit" For PRs that introduce new workflow primitives, skill files, architectural conventions, or MCP tool surfaces, reviewer MUST verify whether other skills / docs / tools need updating to reference the new pattern. Specific checks:
AGENTS_STARTUP.md§9 (Workflow skills) need updating?The §8 check would have caught #10155's ticket-intake gap.
Acceptance Criteria
pr-review-guide.md§3 updated with explicit score-deduction justification requirement (with acceptable / unacceptable example forms)assets/pr-review-template.md) updated with zero-issue-PR semanticsOut of Scope
ticket-intake/pull-request/epic-reviewpattern[EVALUATION_METRICS]category list itself — current categories are fine; the gap is in how they're usedAvoided Traps
Related
.agent/skills/epic-review/references/epic-review-workflow.md§8 — cross-model asymmetry framing that predicted the rubber-stamp outcome.agent/skills/pr-review/— files to be modified71dc3cd8-d39d-48e1-ac62-e240ca67d1a5(this session's workflow planning arc)Origin Session ID: 71dc3cd8-d39d-48e1-ac62-e240ca67d1a5