Epic-resolution skill + Substrate Evidence Ladder graduation (Discussion #10697)

Origin Session ID: cce1fea5-32ff-410c-b820-2e9a27b3cd51

Graduation artifact for Discussion #10697. Mental model per @tobiu: "turn friction into gold" — convert the friction surfaced by PR #10696 / issue #10677 (rubber-stamp review missed substrate-truth violation, mock-bin tests promoted to live-substrate proof, broadcast "components look solid" treated as closeout) into durable workflow artifacts.

Driving question (canonical trigger)

"we resolved all epic subs, are we done now?"

The new closeout skill answers this rigorously rather than by intuition / broadcast claim.

Outcomes the skill must produce

Per @tobiu's framing:

1. Verify the epic is done + recommend close (RECOMMEND_CLOSE_COMPLETED), human acts, OR
2. Add more subs + coordinate work with peers (RECOMMEND_CREATE_MISSING_SUBS), with owner identification + A2A coordination

Edge variants: RECOMMEND_KEEP_OPEN, RECOMMEND_RETIRE_OR_SUPERSEDE.

Convergence summary across OQ1-OQ6

After @neo-gpt's #10697 ideation + my OQ5 + GPT's OQ6 + Gemini's primary-reviewer pass (Approved):

Prescription

Five artifacts in the same PR (small-map / deep-reference shape):

1. New skill epic-resolution at .agents/skills/epic-resolution/

   • SKILL.md (lightweight router; YAML frontmatter + view_file directive)
   • references/epic-resolution-workflow.md (heavy payload: triggers, concurrency guard via discipline-layer mutex on epic comments, matrix-population, four verdict recommendations, A2A coordination on RECOMMEND_CREATE_MISSING_SUBS)
   • Symlink at .claude/skills/epic-resolution
   • AGENTS.md §21 entry: trigger condition "last required sub closes / peer broadcasts epic-readiness / before close as COMPLETED"

2. New reference file learn/agentos/evidence-ladder.md

   • L1-L4 ladder definitions (Static contract / Mock dispatch / Live non-destructive probe / Operator-gated destructive handoff)
   • Sandbox-ceiling vs achievable-ceiling distinction
   • Matrix schema: Parent AC | Required evidence | Owning sub(s) | Delivered PR(s) | Achieved evidence | Residual state
   • Close-target Resolves rule (OQ3 third option)

3. pr-review skill amendment — append two sections to existing review template (assets/pr-review-template.md):

   • ### Evidence Audit — reviewer fills achieved-evidence vs close-target-required vs sandbox-ceiling per PR body declaration
   • ### Source-of-Authority — reviewer citations of operator/peer authority must link source comment-id, A2A messageId, or [paraphrase] mark

4. pull-request skill amendment — 1-line evidence declaration template added to the PR body section structure (Evidence: L<X> → L<Y> required. Residual: AC<N> [#NNNN].)

5. ideation-sandbox skill amendment (narrowed per @neo-gpt's verification) — §4 already supports [GRADUATED_TO_TICKET] marker. §5 prose was Epic-biased; rebalance to say graduation target may be Epic, standard ticket, or rare direct-PR depending on scope. Empirical anchor: this very Discussion (#10697) graduated to ticket #10698 (single bounded artifact), not an Epic.

Acceptance criteria

1. epic-resolution skill scaffolded per .agents/skills/create-skill/references/skill-authoring-guide.md (lightweight SKILL.md router + heavy references payload + symlink). ✅ Verification checklist: one SKILL.md, YAML frontmatter, heavy content in references/, explicit path in router body, .claude/skills/ symlink.
2. Concurrency guard: discipline-layer mutex via in-progress claim comment on the epic; no new state-file primitive needed (lighter than original ticket scope sketch).
3. Verdict authority: skill produces RECOMMENDATIONS only; never autonomously closes the epic. §0 Invariant 1 parallel.
4. Empirical test: skill applied to Epic #10671 produces a structurally complete matrix with RESIDUAL_L4 (AC5 verify-effect across #10676/#10695/#10696) + BLOCKER state of #10679 + verdict KEEP_OPEN.
5. Cross-reference between pr-review Evidence Audit section and learn/agentos/evidence-ladder.md matrix definitions.
6. AGENTS.md §21 trigger entry for epic-resolution + Skill Trigger Pre-Flight bullet.
7. Test evidence: structural verification per skill-authoring-guide.md Verification checklist.

Avoided traps

• Don't bloat epic-review — entry-pass and exit-pass have different agents firing them at different times; sibling skill with shared matrix schema is correct (per GPT refinement, accepted by my OQ6 challenge).
• Don't autonomously close epics — verdict recommendations only; close as completed is human-only per §0 parallel.
• Don't treat "broadcast: components look solid" as closeout — it's a TRIGGER for closeout reconciliation, not the closeout itself. Empirical anchor: Gemini's 15:24:14Z #10671 broadcast.
• Don't make matrix subjective — fixed columns. Reviewer audit is mechanical given the columns.
• Don't gate skill on every PR — narrow trigger (AC-shape includes verify-effect on uncovered surface) keeps review cost low.
• Don't introduce a new state-file lock primitive when discipline-layer mutex suffices — initial ticket sketch proposed harnessLifecycle.mjs-style primitive; on reflection, in-progress claim comments + 30-min cooldown + optional primary-owner restriction is enough. Empirical anchor: epic comments are the natural mutex substrate.
• Don't autonomously create new subs on RECOMMEND_CREATE_MISSING_SUBS — recommend + A2A propose owners; operator authorizes; assigned owner files via ticket-create.

Empirical anchor

Friction event: PR #10696 / issue #10677 cycle (substrate-truth correction → cross-adapter cleanup → re-review → empirical verification gap). Discussion #10697 is the substrate-evidence-ladder ideation that synthesized the friction. This ticket is the graduation artifact.

Discussion convergence comments:

• My OQ1-OQ4 + OQ5 challenges: DC_kwDODSospM4BAHLS
• My OQ6 challenges + Epic #10671 application: DC_kwDODSospM4BAHMe
• My graduation synthesis: DC_kwDODSospM4BAHNu

Related

• #10697 (parent Discussion)
• #10696, #10677 (motivating PR + close-target)
• #10671 (empirical-test epic for the new skill)
• #10324 (close-target audit existing precedent — generalized by this artifact)
• feedback_peer_cited_authority_neutral_ask (memory captured during the cycle, source for OQ-2 Source-of-Authority section)