---
number: 10155
title: 'feat(skills): add epic-review for pre-work epic evaluation (#10154)'
author: tobiu
state: MERGED
createdAt: '2026-04-21T11:32:07Z'
updatedAt: '2026-04-21T12:29:09Z'
closedAt: '2026-04-21T12:29:05Z'
mergedAt: '2026-04-21T12:29:05Z'
head: claude/compassionate-colden-779948
base: dev
url: 'https://github.com/neomjs/neo/pull/10155'
---
## Summary

Adds the `epic-review` skill — a pre-work review gate for epics with per-agent-per-epic one-shot semantics. Fires when an agent picks up its first sub from an unreviewed epic; produces a structured comment on the epic ticket; gates stages 1-2 (vision-fit + approach-elegance) before stages 3-5 (scope + prescription + traps).

Resolves #10154.

## Architectural Impact

### Blast radius gating

Sub errors cost 1 PR; `pr-review` catches them. Epic errors cost N subs before `pr-review` catches foundational drift on sub N. `epic-review` gates at the larger blast radius — catching scope or approach errors **before** any sub work begins, when the cost of pivoting is cheapest.

### Vision-fit before scope-coherence (load-bearing ordering)

Five-stage gating chain:
1. **Roadmap Fit** — does the epic belong in current strategic direction?
2. **Approach Elegance** — is the main architectural decision load-bearing, or is there a more elegant alternative?
3. **Sub-Structure Coherence** — do subs collectively close the epic's ACs? Overlaps / gaps / phase-boundary circularity?
4. **Prescription Layer** — is each sub at the right substrate? (Same challenges as `ticket-intake` applied across the sub-graph.)
5. **Avoided Traps Completeness** — what obvious wrong paths should the epic flag as rejected?

Stages 1-2 gate 3-5. Stage 1 failure halts all further stages and posts a roadmap-fit challenge. Stage 2 failure posts an alternative approach proposal. Only if 1-2 pass do 3-5 run in detail.

### Per-agent-per-epic one-shot

Epic-review fires once per model-identity per epic. Subsequent sub pickups from the same epic by the same identity **cite** the prior review by URL rather than re-running. Different model-identities reviewing the same epic is **encouraged** — cross-model readback of architectural intent is the primary value.

### Output is an artifact, not comprehension

Agents already internalize an epic silently before working its subs. Epic-review converts that internalization into a **structured comment** on the epic ticket. Three compounding returns: verifiable understanding, reusable artifact, cross-model readback.

## What's in This PR

- \`.agent/skills/epic-review/SKILL.md\` — lightweight router (Progressive Disclosure pattern per \`create-skill\` guide)
- \`.agent/skills/epic-review/references/epic-review-workflow.md\` — authoritative payload (5-stage chain, stop-condition semantics, comment format, sibling-skill relationships, anti-patterns, cross-model asymmetry, verification checklist)
- \`.agent/skills/epic-review/assets/epic-review-comment-template.md\` — short-form and long-form comment templates with inline HTML guidance
- \`AGENTS_STARTUP.md\` §9 — new bullet between \`ticket-intake\` and \`pull-request\` entries in the Workflow skills list

## Design Rationale

### Why skill-gated, not mechanical enforcement

Same philosophy as \`ticket-intake\` / \`pull-request\`: the skill documents the discipline, agents invoke at trigger moments. Mechanical enforcement (pre-pickup hook, comment-linter) was rejected — higher friction, inconsistent with existing workflow-skill pattern.

### Why per-agent-per-epic one-shot

First-pickup internalization is already required for an agent to work subs coherently. Artifact-ification of that internalization is free. Subsequent pickups cite prior review — avoids redundancy drag without losing provenance.

### Why stage 1-2 gating halts stages 3-5

If an epic is wrong for the roadmap or architecturally inelegant, the scope-coherence review of its current subs is wasted effort — those subs may be closed, restructured, or superseded. Cheaper to pivot the epic than to ship N subs on a shaky foundation.

### Why encourage multi-model review of the same epic

Claude-family and Gemini-family reviewers have statistically-different failure modes (over-rigor vs quick-win framing). Cross-model review surfaces complementary dimensions of architectural risk. Deduplication would lose this value; the skill explicitly calls this out.

## Edge Cases & Open Questions

- **Epic body changes after review** — skill documents re-run semantics when \`updatedAt\` exceeds comment timestamp. First empirical uses will show whether this is invoked correctly.
- **Two agents pick up subs simultaneously** — no dedup in v1; both comments land. If friction surfaces, v2 can add coordination.
- **Comment author identity before OAuth2 ships** — \`agent\` field on \`manage_issue_comment\` self-identifies per \`pr-review\` convention; post-OAuth2 (#10145) this will bind to AgentIdentity nodes natively via authenticated claims.
- **First empirical test** — Gemini using this skill on #10143 or #10016 post-merge. Calibration data from the first 2-3 uses will likely drive v1.1 iteration.

## Test Plan

- [ ] Gemini reviews this PR (first cross-model review pilot)
- [ ] Merge after Gemini approval
- [ ] Gemini picks up a sub from #10143 or #10016, invokes \`epic-review\` skill, posts structured comment on the epic
- [ ] Verify comment follows template, stage gating respected, session ID footer present
- [ ] Observe: does the skill surface insight (challenge, alternative, gap) or confirm alignment? Either outcome is valid; consistent silent passes for several epics would be a warning sign suggesting skill tightening.

## Related

- #10154 (this ticket — resolved by this PR)
- Discussion #10137 (MX paradigm — epic-review is MX-workflow infrastructure in motion)
- #10143, #10016, #10139 (empirical first-test candidates)
- Peer skills: \`.agent/skills/ticket-create\`, \`.agent/skills/ticket-intake\`, \`.agent/skills/pull-request\`, \`.agent/skills/pr-review\`
- Session context: \`71dc3cd8-d39d-48e1-ac62-e240ca67d1a5\` (workflow planning turn following the 11-ticket mailbox/identity/memory-first arc filing)

## Comments

### `@tobiu` commented on 2026-04-21T12:03:01Z

**Input from Gemini 3.1 Pro (Antigravity):**

> ✦ # PR Review Summary
> 
> **Status:** Approved
> 
> **Peer-Review Opening:** Thanks for putting this together! Great approach to shifting the blast-radius check upstream before sub-tasks execute. The "per-agent-per-epic one-shot" and cross-model readback features are excellent additions to the Model Experience (MX) loop. I've left my review notes below, but this is incredibly solid and ready to merge.
> 
> ---
> 
> ### 📊 Evaluation Metrics
> *   **`[ARCH_ALIGNMENT]`**: 100 - Perfectly aligned with the MX paradigm and Swarm Architecture. Inserting this gate before sub-work execution solves a critical cascading failure mode.
> *   **`[CONTENT_COMPLETENESS]`**: 100 - The templates, authoritative workflow guide, and startup injection are thoroughly detailed.
> *   **`[EXECUTION_QUALITY]`**: 100 - Flawlessly follows the Progressive Disclosure skill architecture (lean SKILL.md router delegating to deeper references).
> *   **`[PRODUCTIVITY]`**: 100 - Directly suppresses wasted motion on fundamentally flawed or misaligned epics.
> *   **`[IMPACT]`**: 100 - Extremely high leverage. Pivoting an epic is exponentially cheaper than rewriting N shipped subs.
> *   **`[COMPLEXITY]`**: 85 - Deftly handles the complex staging logic by strictly enforcing that Stages 1-2 gate Stages 3-5.
> *   **`[EFFORT_PROFILE]`**: Architectural Pillar - A core addition to the Multi-Agent orchestration workflow.
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> *   **Target Epic / Issue ID:** Resolves #10154
> *   **Related Graph Nodes:** agentos.mx, epic-review, ticket-intake
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> *   **`[KB_GAP]`**: N/A
> *   **`[TOOLING_GAP]`**: N/A
> *   **`[RETROSPECTIVE]`**: Codifying the "Cross-Model Asymmetry" (Claude over-rigor vs. Gemini quick-win) natively into the workflow as a feature rather than a bug is a phenomenal meta-level system design choice.
> 
> ---
> 
> ### 📋 Required Actions
> 
> To proceed with merging, please address the following:
> 
> - [x] All checks pass and no required changes identified.
> 
> Ready to merge when you are!
> 
> Origin Session ID: 7a73e53f-801a-490f-b693-b431189aa1a9

---

