---
id: 10156
title: 'pr-review: add depth-floor mandates to prevent rubber-stamp approvals'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - tobiu
createdAt: '2026-04-21T13:02:34Z'
updatedAt: '2026-04-21T14:03:40Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10156'
author: tobiu
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-21T14:03:40Z'
---
# pr-review: add depth-floor mandates to prevent rubber-stamp approvals

# 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:

1. **`[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.

2. **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.

3. **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.

4. **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
- [ ] `pr-review-guide.md` §3 updated with explicit score-deduction justification requirement (with acceptable / unacceptable example forms)
- [ ] New §7 "Depth Floor" section documents minimum-one-challenge requirement with "documented search" fallback language
- [ ] §5 and template (`assets/pr-review-template.md`) updated with zero-issue-PR semantics
- [ ] New §8 "Cross-Skill Integration Audit" section with explicit check list
- [ ] Anti-patterns surface in guide or template: pre-ticked placeholder checkbox; unexplained score deduction; fully affirming review with no documented search; missing cross-skill integration check
- [ ] First post-enhancement PR review demonstrates improved rigor (empirical validation via actual usage, not fixture test)

### 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


## Timeline

- 2026-04-21T13:02:35Z @tobiu added the `documentation` label
- 2026-04-21T13:02:35Z @tobiu added the `enhancement` label
- 2026-04-21T13:02:35Z @tobiu added the `ai` label
- 2026-04-21T13:05:44Z @tobiu assigned to @tobiu
- 2026-04-21T13:08:50Z @tobiu cross-referenced by PR #10157
- 2026-04-21T13:34:26Z @tobiu referenced in commit `7766e94` - "feat(skills): add template slots for Depth Floor + Cross-Skill Integration Audit (#10156)"
- 2026-04-21T13:41:12Z @tobiu referenced in commit `f4321ae` - "feat(skills): clarify pr-review metric categories (evaluative vs descriptive) (#10156)"
- 2026-04-21T14:03:40Z @tobiu referenced in commit `111fa26` - "feat(skills): add depth-floor mandates to pr-review (#10156) (#10157)

* feat(skills): add epic-review for pre-work epic evaluation (#10154)

* feat(skills): add depth-floor mandates to pr-review (#10156)

* feat(skills): add template slots for Depth Floor + Cross-Skill Integration Audit (#10156)

* feat(skills): clarify pr-review metric categories (evaluative vs descriptive) (#10156)"
- 2026-04-21T14:03:41Z @tobiu closed this issue
- 2026-04-21T15:08:29Z @tobiu referenced in commit `098a490` - "feat(ai): lift Memory + Session to first-class graph nodes (#10151) (#10161)

* feat(skills): add epic-review for pre-work epic evaluation (#10154)

* feat(skills): add depth-floor mandates to pr-review (#10156)

* feat(skills): add template slots for Depth Floor + Cross-Skill Integration Audit (#10156)

* feat(skills): clarify pr-review metric categories (evaluative vs descriptive) (#10156)

* feat(ai): lift Memory + Session to first-class graph nodes (#10151)

* fix(ai): protect SESSION and MEMORY from getOrphanedNodes cleanup (#10151)"

