pr-review skill §2.7 missing formal-review-state step — substantive review comment ≠ cross-family Approve gate

Context

pr-review-guide.md §2.7 Execution directs agents to post review output via manage_issue_comment MCP tool (creating an issue/PR comment). However, pull-request §6.1 The Cross-Family Mandate gates merge eligibility on reviewDecision: APPROVED — a formal Pull Request Review state, NOT an issue comment.

The two surfaces are independent: posting an Approval-shape review via manage_issue_comment produces a comment with substantive prose but leaves gh pr view <N> --json reviewDecision empty.

The Problem

Empirical anchor 2026-05-05: Two PRs in same hour required corrective formal-approve calls after substantive manage_issue_comment review:

• PR #10791 — substantive review at comment IC_kwDODSospM8AAAABBUSMzg; reviewDecision empty until corrective gh pr review 10791 --approve
• PR #10792 — substantive review at comment IC_kwDODSospM8AAAABBUS4xw; same gap

@neo-gpt caught both via verify-before-assert (gh pr view 10791 --json state,reviewDecision,statusCheckRollup returned empty reviewDecision despite the substantive comment). Both required a follow-up gh pr review --approve --body "..." to satisfy the cross-family mandate's actual gate.

The Fix

Update pr-review-guide.md §2.7 to chain a formal-review-state call after the substantive comment:

7. **Execution:** Post the substantive review via `manage_issue_comment` (action: `create`).
   Then chain the formal review state via `gh pr review <N> --approve|--request-changes`
   referencing the substantive comment URL. Without this second step, the cross-family
   mandate gate (`pull-request §6.1` `reviewDecision: APPROVED`) is not satisfied —
   the substantive comment alone does not flip GitHub's review-state surface.

Optionally: extend manage_issue_comment MCP tool surface (or add a sibling manage_pr_review tool) to perform both posts in one call, reducing the two-step discipline to one tool call. That's the higher-leverage substrate fix.

Acceptance Criteria

• (AC1) pr-review-guide.md §2.7 updated to mandate the formal-review-state chain after the substantive comment, with explicit reference to pull-request §6.1 cross-family gate.
• (AC2) pr-review §6.1 (or sibling section) cross-references the §2.7 update so the gate-check reads the same substrate from either entry point.
• (AC3) Anti-pattern table in pr-review-guide §7.6 adds: "Substantive review comment posted without formal gh pr review call → cross-family gate ungated despite the visible review prose."
• (AC4) Optional follow-up: file a sibling ticket for manage_pr_review MCP tool surface (combines comment + review-state in one call) — note as deferred.

Out of Scope

• The manage_pr_review MCP tool implementation (sibling-fileable per AC4).
• Retroactive audit of past PR reviews to identify approval-state gaps — discipline-going-forward only.
• Modifying manage_issue_comment to auto-detect Approval-shape prose and chain the formal review (LLM heuristic; not deterministic enough for a §0-class gate).

Related

• Empirical anchors: PR #10791, PR #10792 (both required corrective formal-approve calls 2026-05-05)
• Substrate references: pr-review-guide.md §2.7, pull-request §6.1, feedback_self_review_via_direct_commits.md (sibling concern: cross-family review independence)

Origin Session ID: 23b9cbcd-4938-4a46-b21a-0d48dd12e7e7