LearnNewsExamplesServices
Frontmatter
id10617
titleClose residual drifts in pr-review §9 / §9.1 substrate (#10615 follow-up)
stateClosed
labels
documentationenhancementai
assignees[]
createdAtMay 2, 2026, 12:53 PM
updatedAtMay 3, 2026, 1:01 PM
githubUrlhttps://github.com/neomjs/neo/issues/10617
authorneo-opus-4-7
commentsCount1
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 3, 2026, 1:01 PM

Close residual drifts in pr-review §9 / §9.1 substrate (#10615 follow-up)

Closeddocumentationenhancementai
neo-opus-4-7
neo-opus-4-7 commented on May 2, 2026, 12:53 PM

Authored by Claude Opus 4.7 (Claude Desktop). Origin Session ID: b1839431-cba1-4b6d-913f-27b09e472e67.

Related: #10615 (parent ticket), #10616 (parent PR — Approve+Follow-Up shape applied at Cycle 2 commentId IC_kwDODSospM8AAAABBBeuEQ)

Why

PR #10616 shipped the §9 Strategic-Fit Step-Back + §9.1 Reviewer-Yield Protocol + Author Pre-Flight Check substrate per #10615 spec. Cycle 2 review applied the new §9 shape recursively (using Approve+Follow-Up to evaluate the PR introducing Approve+Follow-Up) — substrate ships, but 7 residual drifts/polish items remain best-tracked-as-follow-up rather than Cycle 3 churn.

This ticket consolidates the post-merge tracking. Three are substrate drifts (file-line cross-ref breakage + wrong cross-ref target + missing empirical anchor); four are polish items (back-link discoverability, anti-pattern table coverage, PR body framing, authority-boundary clarification).

What

A. Substrate Drifts (must-fix; mechanical)

A1. pull-request-workflow.md line 229 — sibling-skill cross-ref still broken

Current:

Rationale: §9 of `pr-review-guide.md` covers the reviewer-side mechanics; this section covers the author-side symmetric hand-off.

Required:

Rationale: §10 of `pr-review-guide.md` covers the reviewer-side mechanics; this section covers the author-side symmetric hand-off.

(§9 in pr-review-guide.md is now Strategic-Fit Step-Back; A2A Comment-ID Hand-off is §10. PR #10616 fixed lines 230 + 232 in this file but missed line 229.)

A2. pr-review-guide.md §9.1 cross-ref points at wrong target

Current §9.1 Reviewer-Yield Protocol opens:

When an author invokes `[REJECTED_WITH_RATIONALE]` per the Review Response Protocol (`pull-request §6.1`)...

Empirical: grep -n '^### 6\.1' .agents/skills/pull-request/references/pull-request-workflow.md → line 139, "The Cross-Family Mandate". [REJECTED_WITH_RATIONALE] is defined in .agents/skills/pull-request/references/review-response-protocol.md §4 (Per-Item Status Tags), NOT in pull-request §6.1.

Required: change cross-ref to review-response-protocol §4 (correct target where [REJECTED_WITH_RATIONALE] is defined).

A3. pr-review-guide.md §9.1 missing empirical anchor

Every audit/protocol section in this guide cites a PR-anchor: §5.2 #9999, §5.3 #10340, §7.4 #10298 + #10371, §8.3 #10155, §8.4 #10397, §9 (#10602 + #10610 + #10607). The new §9.1 has none.

Required: add closing line citing PR #10607 as the deadlock pattern (reviewer escalated theoretically, author had operator-intent evidence but did not invoke [REJECTED_WITH_RATIONALE], corrective work required PR #10611).

B. Polish (lower priority; tracked here to prevent loss)

B1. review-response-protocol.md §1 Author Pre-Flight Check — back-link to §9.1

Currently §1 references the response shape but doesn't tell authors that reviewers have a reciprocal Yield Pre-Flight per pr-review-guide §9.1. Adding a back-link closes symmetric discoverability — authors invoking [REJECTED_WITH_RATIONALE] should know the protocol mandates reviewers yield to substrate-grounded evidence.

B2. pr-review-guide.md §7.6 anti-pattern table — Reviewer-Yield row

§7.6 anti-patterns table doesn't include "Re-escalating Required Action without superior empirical evidence after [REJECTED_WITH_RATIONALE]". Adding the row surfaces §9.1 from the §7 Depth Floor entry surface.

B3. PR #10616 body framing nit

Current: "Implements the reviewer step-back meta-audit layer to break the 8-cycle rigor trap."

Empirical: AC2 (next 5 PRs use extended Status field) is post-merge measurement — whether the substrate breaks the trap is empirical, not assertable in PR body. Tighten to "TARGETS the 8-cycle pattern" per §7.4 rhetorical-drift discipline.

(Resolvable as PR body edit even before this ticket lands; flagging here for tracking.)

B4. pr-review-guide.md §9 Drop+Supersede authority boundary

Current §9 Drop+Supersede shape says "Close the PR + close the ticket + file a superseding ticket with corrected scope." Ambiguous whether the reviewer executes the closes or recommends to the author. Per §0 Critical Gate 1, agents don't execute merges, but they DO close issues routinely. Clarification needed: is reviewer-closure of PR/ticket explicitly authorized for Drop+Supersede, or is it author-recommendation territory?

How

Single PR addressing A1-A3 + B1-B4. Estimated diff: ~25-30 lines across 3 files (pull-request-workflow.md + pr-review-guide.md + review-response-protocol.md). No runtime substrate; pure skill-content updates.

Acceptance Criteria

  • AC1: pull-request-workflow.md line 229 cross-ref points at §10 of pr-review-guide.md (verifiable via grep).
  • AC2: pr-review-guide.md §9.1 cross-ref points at review-response-protocol §4 (correct target).
  • AC3: pr-review-guide.md §9.1 carries an explicit empirical anchor citing PR #10607.
  • AC4: review-response-protocol.md §1 Author Pre-Flight Check has a back-link to pr-review-guide §9.1 Reviewer-Yield Protocol.
  • AC5: pr-review-guide.md §7.6 anti-pattern table has a row for "Re-escalating Required Action without superior empirical evidence after [REJECTED_WITH_RATIONALE]".
  • AC6: PR #10616 body framing tightened ("break" → "TARGETS") OR explicitly deferred with rationale.
  • AC7: §9 Drop+Supersede authority-boundary clarified (reviewer-execution vs author-recommendation explicit).

Avoided Traps

  • Scope-add to PR #10616 mid-cycle 2 (rejected): Would have triggered Cycle 3 churn for 7 mechanical/polish items — exactly the over-rigor pattern §7.2 names. Approve+Follow-Up was the right shape.
  • Treat as 7 separate tickets (rejected): Would fragment the residual-drift tracking. Single ticket consolidates the substrate-cleanup work and provides cohesive review surface.
  • Defer indefinitely without ticket (rejected): The new §9 Approve+Follow-Up shape REQUIRES a follow-up ticket — otherwise it's just "Approve" with hidden debt. Discipline-defining ticket on the discipline-defining PR.

Five-Stage Challenge Chain

  1. Hypothesis: Are the 7 items genuinely follow-up-track, or some load-bearing for #10616 merge? PASS — Cycle 2 review's empirical analysis (file-line citations + grep-verification) confirmed all 7 are content/discoverability drifts, not correctness blockers; substrate ships functional.
  2. Premise: Is the asymmetry-symmetry framing real or contrived? PASS — Tobi surfaced the deadlock vulnerability, Gemini implemented §9.1 in response, the missing back-link/anti-pattern-row is the visible-cost of asymmetric-discoverability.
  3. Prescription: Are the file-line edits the right fix shape? PASS — A1-A3 are mechanical line edits; B1-B4 are skill-content additions consistent with prevailing patterns in same files. Each AC verifiable via grep or inspection.
  4. ROI: Is the work worth the ticket-overhead? PASS — Approve+Follow-Up shape REQUIRES this ticket per the new §9; this is the discipline-defining application of the discipline this PR ships. Filing it is itself the substrate validation.
  5. Risk: Could this introduce regression? VERY LOW — Pure skill-content additions/fixes; no runtime substrate; no test surface; sibling files already grep-anchored.

Origin Session ID

b1839431-cba1-4b6d-913f-27b09e472e67 (Claude Opus 4.7, Claude Desktop, 2026-05-02 morning swarm-coordination session that filed #10615 + reviewed PRs #10612 and #10616).

tobiu referenced in commit 388ec2e - "docs(agents): close residual drifts in pr-review §9 / §9.1 substrate (#10617) (#10618) on May 3, 2026, 1:01 PM
tobiu closed this issue on May 3, 2026, 1:01 PM