Add epic-review skill: vision-fit gate + sub-structure review for new epics

Context

During 2026-04-21 workflow planning session (after filing 11 sub-tickets across #10143, #10016, #10139), identified asymmetric cost between sub-ticket errors and epic errors:

• Sub error: blast radius = 1 PR. PR-review catches. ticket-intake provides the sub-level gate.
• Epic error: blast radius = N subs. By the time PR-review catches drift on sub N, subs 1..N-1 have already pulled in the same wrong assumption. No existing skill gates at the epic level.

Additional load-bearing insight: an epic can pass internal-coherence checks (scope closes, phases align, ACs exist) while still being the wrong epic — misaligned with roadmap, or correct problem with non-elegant approach. Vision-fit gate must come before scope-coherence review; an inelegant approach passing structural review wastes N-sub worth of effort.

The Problem

When a new epic is filed or picked up:

• No structured check that it belongs in current roadmap (could duplicate #10030 / #10119 scope; could be premature)
• No challenge to "is the main approach elegant?" (scope-coherent ≠ architecturally-right)
• Agents picking up subs internalize the epic silently; no artifact of understanding exists, no cross-model readback
• Skill gap: ticket-intake operates at sub level, ticket-create at creation moment. Epic-level vision-fit + pre-work review has no home.

The Architectural Reality

• .agent/skills/ticket-intake/SKILL.md — Pre-Execution Reflection Gate for sub-tickets. Validates architectural ROI + duplicate sweep. Sub-scope.
• .agent/skills/ticket-create/SKILL.md — Five-stage challenge chain at creation. Title hygiene, Fat Ticket body, label rules. Works at ticket-birth moment, not agent-pickup moment.
• .agent/skills/pr-review/SKILL.md — Execution-drift review. Operates after work lands, not before it starts.
• No skill gates at epic-pickup by an agent that will work its subs.

The Fix

New skill .agent/skills/epic-review/SKILL.md + .agent/skills/epic-review/references/epic-review-workflow.md. Triggered when an agent picks up its first sub from an unreviewed epic (per-agent-per-epic one-shot; subsequent pickups cite the prior review). Output: structured comment posted to the epic ticket.

Five-stage chain (sequential; stage-1 failure halts the review):

1. Roadmap Fit. Does the epic belong in current strategic direction? Conflict with or duplicate an in-flight epic? Premature (depends on unshipped work)? Stops here if answer is no — comment is a roadmap-fit challenge, not a scope review.
2. Approach Elegance. Is the main architectural decision load-bearing? Is there a more elegant alternative that wasn't considered? Does the approach reuse existing substrate or invent parallel substrate? Stops here with alternative proposals if inelegant — cheaper to pivot the epic than ship N subs on a shaky foundation.
3. Sub-Structure Coherence. Do the subs collectively close the epic's success criteria? Any gaps or overlaps? Phase-boundary circularity?
4. Prescription Layer. For each sub, right layer? Service-boundary cleanliness? (Same five-stage chain from ticket-intake but applied across the sub-graph.)
5. Avoided Traps Completeness. What obvious wrong paths should the epic name as rejected?

Output format: structured comment with fixed sections per stage. If stage 1 or 2 fails, comment is short and names the challenge/alternative; stages 3-5 skip. If 1-2 pass, stages 3-5 produce detailed scope review.

Acceptance Criteria

• .agent/skills/epic-review/SKILL.md exists with authoritative description triggering on first-sub-pickup from unreviewed epic
• .agent/skills/epic-review/references/epic-review-workflow.md documents the five-stage chain with stage-gating semantics
• AGENTS_STARTUP.md §9 updated to reference the skill in the Workflow skills list, alongside ticket-create / ticket-intake / pull-request / pr-review
• Per-agent-per-epic one-shot semantics documented explicitly (avoid redundant comments when same agent picks up multiple subs from same epic)
• Structured comment template included in assets/ or inline reference
• First empirical use on #10143 / #10016 / #10139 produces a structured comment that surfaces at least one insight (either alignment-confirmation or substantive challenge)

Out of Scope

• Mechanical enforcement (comment-linter, pre-sub-pickup hook) — discipline via skill doc, not mechanism. Consistent with ticket-intake / pull-request pattern.
• Cross-agent epic-review deduplication in v1 (if two agents review same epic, both comments land; no dedup layer yet)
• Retroactive application to all existing epics (skill fires on future pickups; retroactive sweep is optional follow-up if value is proven)

Avoided Traps

• Scope-coherence-only review (skipping vision-fit). Rejected. Epic can be internally coherent while wrong-for-roadmap; vision-fit gate must come first, not as optional appendix.
• Running all stages unconditionally. Rejected. If stage 1 fails (wrong epic), stages 3-5 waste effort rehearsing sub-coherence of an epic that shouldn't ship in current form. Gate structure is load-bearing.
• Per-sub-pickup review comments. Rejected. Per-agent-per-epic one-shot; subsequent pickups cite prior review. Avoids redundancy drag.
• Heavyweight review gate requiring human sign-off. Rejected. Gemini's empirical need to understand the epic to work subs is what makes this a free artifact — it fires naturally, not as imposed process tax.

Related

• Peers: .agent/skills/ticket-intake, .agent/skills/ticket-create, .agent/skills/pr-review, .agent/skills/pull-request
• Broader arc: #10119 (Neo Agent Harness) — epic-review is part of MX-workflow infrastructure but standalone, not a child of #10119
• First empirical test: Gemini uses the skill on #10143 or #10016 after merge — the cross-model validation pilot
• Session context: workflow brainstorm turn in session 71dc3cd8-d39d-48e1-ac62-e240ca67d1a5, immediately after 11-ticket mailbox/identity/memory-first arc filing

Origin Session ID: 71dc3cd8-d39d-48e1-ac62-e240ca67d1a5