Strengthen A2A commentId hand-off discipline (reflex + cold-cache exception)

Context

Empirical observation from session 2026-04-26 (Origin Session ID: aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343): cross-family PR reviewer @neo-opus-ada missed the A2A commentId hand-off discipline (pr-review-guide.md §9) across 5+ review cycles on PRs #10371 and #10375 despite having read the guide before drafting reviews. @tobiu surfaced the gap explicitly, prompting calibration. The discipline IS codified — the failure was reflexive-application, not knowledge.

The Problem

The A2A commentId hand-off protocol (originated in #10272) is structurally complete on the substrate side: manage_issue_comment returns commentId, get_conversation accepts a comment_id selector, reviewer-side guide §9 + author-side workflow §8.1 codify the propagation. But three discipline-layer gaps cause the rule to silently miss-fire:

1. Optimization framing, not invariant framing. §9's problem statement reads as "burns more tokens" — sounds like an efficiency improvement, not a load-bearing protocol. Compare to AGENTS.md §0.5 ("No skipping add_memory at end of turn — Forgetting = permanent data loss") which IS framed as a Critical Gate and never gets missed.
2. End-of-guide placement is attention-evicted by template loading. §9 is the last section of a 9-section guide. By the time a reviewer loads §6's template into working context to draft, §9's reminder is no longer in attention.
3. No Pre-Flight Check shape. AGENTS.md §3 Pre-Commit Pre-Flight Check is empirically the strongest reflex primitive in this codebase — Gate violations get caught reliably because the checklist forces explicit commitment statements. The A2A commentId hand-off has no equivalent shape.

A fourth gap, separately surfaced during @tobiu's calibration: §9 doesn't address the cold-cache case. CommentId-scoped fetch is the warm-cache path (reviewer has prior cycle context loaded). When a fresh session bootstraps OR a different agent picks up a cycle handoff, full-thread fetch is required for grounding. Without explicit guidance, agents either (a) rigidly use commentId fetch and miss context, or (b) over-fetch on principle and defeat the optimization. Same dichotomy shape as the boot-pull-vs-sunset-pull lifecycle distinction (AGENTS_STARTUP §0 vs session-sunset skill body Step 1) — warm-cache vs cold-cache paths fill different gaps.

The Architectural Reality

• Reviewer-side codification: .agent/skills/pr-review/references/pr-review-guide.md §9 (A2A Comment-ID Hand-off Protocol).
• Author-side codification: .agent/skills/pull-request/references/pull-request-workflow.md §8.1 (A2A Comment-ID Propagation, Author Side).
• Per-turn awareness signpost: AGENTS.md §21 Workflow Skills awareness table — currently has rows for pr-review and pull-request but neither row mentions the post-comment A2A hand-off discipline.
• Pre-Flight Check pattern reference: AGENTS.md §3 (commits) and AGENTS.md §4.2 (memory) — proven reflex primitives. Reuses the same shape, no new primitive needed.

The Fix

Three-pronged doc-layer strengthening (no code changes):

1. Post-Flight Check shape in the skill bodies

Add to both .agent/skills/pr-review/SKILL.md and .agent/skills/pull-request/SKILL.md a short mandatory Post-Flight reminder mirroring the AGENTS.md §3 / §4.2 Pre-Flight pattern. Agents must internally state in their reasoning before yielding turn that they captured commentId + sent the A2A ping. ~3 lines per file.

2. Cost anchor + cold-cache exception in the references guides

Strengthen pr-review-guide.md §9 (and reference from pull-request-workflow.md §8.1):

• Add an empirical anchor (e.g., this session's PR #10371 Cycle 3 thread token-budget cost vs commentId-scoped fetch cost — concrete ratio captured for posterity).
• Add new §9.4 Cold-Cache Exception subsection covering the four cold-cache cases: fresh session bootstrap, Cycle 1 review, cross-agent handoff, missed/lost ping fallback. Frame as warm-cache vs cold-cache dichotomy parallel to the boot-pull-vs-sunset-pull lifecycle distinction.
• Reframe the §9 problem statement from optimization-language ("burns tokens") to invariant-language ("breaks linear-cost scaling — silent waste compounding per cycle").

3. AGENTS.md §21 row updates

Update the existing pr-review and pull-request rows so the discipline is part of the per-turn awareness signpost (survives context-pruning):

• pr-review row: append , post-comment A2A commentId hand-off (reviewer→author) per guide §9
• pull-request row: append , author-side A2A commentId hand-off on response comments per workflow §8.1

Acceptance Criteria

• .agent/skills/pr-review/SKILL.md updated with Post-Flight Check block referencing guide §9.
• .agent/skills/pull-request/SKILL.md updated with Post-Flight Check block referencing workflow §8.1.
• .agent/skills/pr-review/references/pr-review-guide.md §9 strengthened: empirical cost-anchor added; new §9.4 Cold-Cache Exception subsection added (covering fresh-session-bootstrap, Cycle-1-review, cross-agent-handoff, missed-ping-fallback); problem statement reframed from optimization to invariant language.
• .agent/skills/pull-request/references/pull-request-workflow.md §8.1 cross-references the new pr-review-guide §9.4 cold-cache exception (DRY — single source of truth lives in the reviewer-side guide).
• AGENTS.md §21 Workflow Skills awareness table updated: pr-review and pull-request rows extended with the A2A hand-off discipline.
• No regressions in existing skill behavior; Progressive Disclosure routing pattern preserved (router stays terse, body content goes in references files).

Out of Scope

• New MCP tool surfaces or substrate-layer changes (the substrate work was completed by #10272).
• Automated detection / linting for missed A2A pings (mechanical-layer enforcement after discipline-layer proves insufficient — premature here).
• Discussion-comment hand-off enrichment (covered separately by #10304).
• A2A discipline strengthening for non-PR-review contexts (mailbox DMs, broadcast routing, Task envelope replies) — different surfaces have different cost profiles; resist premature generalization.

Avoided Traps

• Bolting commentId capture into AGENTS.md as a Critical Gate (§0.6). Tempting to elevate to invariant level, but Critical Gates are reserved for mechanically-verifiable rules with no conditional exceptions. The cold-cache exception means commentId-scoped fetch is conditionally NOT the right action; that's incompatible with Gate semantics. Discipline-layer Pre-Flight Check is the right primitive.
• Adding a parallel rule for non-PR contexts. A2A pings happen in many surfaces. The PR-review and PR-author surfaces are where the cycle-cost compounding bites; other surfaces have different cost profiles. Resist generalizing prematurely; let usage drive future codification.
• Removing the §9 problem statement entirely. The "burns tokens" framing is correct, just under-load-bearing. Strengthen, don't replace.
• Wording the new §0 fold-in clarification (in PR #10375) as "Boot vs. Sunset Symmetry". The whole calibration was that the two pulls are NOT symmetric — they are complementary. Naming the section "Symmetry" risks re-introducing the misconception. Already flagged on PR #10375; this ticket is a separate concern but shares the documentation-discipline lesson: when the calibration is specifically about NOT-X, naming the codified section "X" inverts the lesson.

Related

• #10272 (CLOSED) — Substrate-side: implemented commentId capture + selector. THIS ticket is the discipline-strengthening on top of that substrate work.
• #10304 (OPEN) — Adjacent: enriches manage_discussion_comment with the same protocol on the discussion-comment surface. Different scope, sibling effort.
• #10371 (OPEN at filing time) — Empirical anchor PR where the discipline gap surfaced (5+ missed cycles).
• #10375 (OPEN at filing time) — Sibling sunset-skill PR where the gap recurred via Critical Gate 2 commit-subject violation; reinforces that Pre-Flight Check shape is the missing primitive.

Origin Session ID: aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343

Retrieval Hint: "A2A commentId hand-off discipline" / "Pre-Flight Check pattern for review-cycle reflex" / "cold-cache exception PR review" / "warm-cache vs cold-cache thread fetch"