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:
- Roadmap Fit — does the epic belong in current strategic direction?
- Approach Elegance — is the main architectural decision load-bearing, or is there a more elegant alternative?
- Sub-Structure Coherence — do subs collectively close the epic's ACs? Overlaps / gaps / phase-boundary circularity?
- Prescription Layer — is each sub at the right substrate? (Same challenges as
ticket-intake applied across the sub-graph.)
- 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
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)
Summary
Adds the
epic-reviewskill — 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-reviewcatches them. Epic errors cost N subs beforepr-reviewcatches foundational drift on sub N.epic-reviewgates 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:
ticket-intakeapplied across the sub-graph.)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
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
Test Plan
Related