Context
A 3-iteration verify-before-assert failure occurred during the review of PR #10632 (2026-05-03). Multiple coordination inputs—own ticket bodies, user statements interpreted as directives, and cross-ticket contract deviations—were treated as substrate-truth without verification. This caused lost-concept compounding and exponential debug cost. This Epic operationalizes the resolutions from Discussion #10634.
The Problem
Agents assume their own previous artifacts (e.g. ticket bodies) are immune to bit-rot or implementation drift. When acting as a reviewer, the author of a ticket often misses Avoided Traps because they hold the architectural intent and fail to verify it against the actual implementation. Furthermore, cross-ticket contracts (e.g., #10625 vs #10632 cycle_id state derivation) are frequently referenced in PR bodies but not empirically verified against the providing ticket's specific spec, leading to contract-vs-implementation drift.
The Architectural Reality
The existing Verify-before-assert mandate (AGENTS.md §2.3) currently lacks explicit coverage for coordination-layer inputs (ticket bodies, A2A claims). The pr-review skill does not enforce a checklist for Avoided Traps from the close-target ticket, nor does it enforce separated provider/consumer checks for contract-bearing cross-references.
The Fix
- Extend
AGENTS.md §2.3 wording to explicitly mandate verify-before-assert on coordination-layer inputs (own ticket bodies, peer claims, user statements).
- Extend
.agents/skills/pr-review/references/pr-review-guide.md with an Avoided-Traps Verification checklist. This fires when the close-target ticket contains an Avoided Traps section, enforcing standard verification depth, with a stricter verification depth mode when the reviewer authored or scoped the ticket.
- Extend
.agents/skills/pr-review/references/pr-review-guide.md with a Cross-Ticket Contract Verification step, triggered by regex-detectable contract-bearing references (e.g., "consumes #N's contract"), enforcing a distinct provider/consumer evidence split.
- (Deferred) Defer the lost-concept compounding metric instrumentation (OQ4) until OQ1-3 generate stable event categories.
Acceptance Criteria
Out of Scope
- Instrumenting metrics for "Iterations-per-discipline-failure" or "Lost-concept-density" is explicitly deferred (OQ4) until the new taxonomy proves stable.
Avoided Traps
- Trap: Limiting the Avoided-Traps check only to the ticket's original author.
Resolution: Make the Avoided Traps checklist universal for any reviewer, but with a stricter verification depth (evidence verification vs standard checklist) for the author.
- Trap: Triggering cross-ticket contract verification on every generic
Related: #N link.
Resolution: Use specific contract-bearing phrasing triggers (e.g., "consumes contract", "uses X's signal") to prevent review noise.
Related
- Discussion #10634 (Originating ideation)
- Discussion #10630 (sibling intent-first workflow)
- PR #10632 (empirical anchor)
Origin Session ID: d28a63c7-a4ec-40ff-aaaa-62d862e031f5
Retrieval Hint: "3-iteration verify-before-assert failure 2026-05-03 substrate-truth coordination-input"
Context
A 3-iteration verify-before-assert failure occurred during the review of PR #10632 (2026-05-03). Multiple coordination inputs—own ticket bodies, user statements interpreted as directives, and cross-ticket contract deviations—were treated as substrate-truth without verification. This caused lost-concept compounding and exponential debug cost. This Epic operationalizes the resolutions from Discussion #10634.
The Problem
Agents assume their own previous artifacts (e.g. ticket bodies) are immune to bit-rot or implementation drift. When acting as a reviewer, the author of a ticket often misses Avoided Traps because they hold the architectural intent and fail to verify it against the actual implementation. Furthermore, cross-ticket contracts (e.g., #10625 vs #10632
cycle_idstate derivation) are frequently referenced in PR bodies but not empirically verified against the providing ticket's specific spec, leading to contract-vs-implementation drift.The Architectural Reality
The existing Verify-before-assert mandate (
AGENTS.md§2.3) currently lacks explicit coverage for coordination-layer inputs (ticket bodies, A2A claims). Thepr-reviewskill does not enforce a checklist for Avoided Traps from the close-target ticket, nor does it enforce separated provider/consumer checks for contract-bearing cross-references.The Fix
AGENTS.md§2.3 wording to explicitly mandate verify-before-assert on coordination-layer inputs (own ticket bodies, peer claims, user statements)..agents/skills/pr-review/references/pr-review-guide.mdwith anAvoided-Traps Verificationchecklist. This fires when the close-target ticket contains an Avoided Traps section, enforcing standard verification depth, with a stricter verification depth mode when the reviewer authored or scoped the ticket..agents/skills/pr-review/references/pr-review-guide.mdwith aCross-Ticket Contract Verificationstep, triggered by regex-detectable contract-bearing references (e.g., "consumes #N's contract"), enforcing a distinct provider/consumer evidence split.Acceptance Criteria
AGENTS.md§2.3 updated with operational verify-before-assert extension wording.pr-review-guide.mdupdated with Avoided-Traps verification trigger and template logic.pr-review-guide.mdupdated with Contract-Bearing Reference trigger and provider/consumer verification template logic.Out of Scope
Avoided Traps
Related: #Nlink. Resolution: Use specific contract-bearing phrasing triggers (e.g., "consumes contract", "uses X's signal") to prevent review noise.Related
Origin Session ID: d28a63c7-a4ec-40ff-aaaa-62d862e031f5
Retrieval Hint:
"3-iteration verify-before-assert failure 2026-05-03 substrate-truth coordination-input"