| name | review-epics |
| description | Review split-epics output against the source plan — coverage, boundaries, ordering, OKF structure, GitHub state — and write a prioritized docs/reviews/<date>-epics-<subject>.md. Use when the user asks to audit, QA, or review created epics against the plan or scope. |
Review Epics
Audit the epic set that split-epics (or define-change) produced against the plan
it came from. The question to answer: could someone run create-issues across these
epics and end up building what the plan actually asked for?
How a review is graded, verified, delegated to another model, and written down is
defined once in ../_shared/review-interfaces.md — read it before starting. The
artifacts under review are governed by ../_shared/pipeline-interfaces.md (epic
schema, status lifecycle, GitHub facts) and ../_shared/bundle-interfaces.md (link
forms, reserved files, language). Judge against those two files directly; an epic is
only malformed relative to what they define. A fourth contract judges nothing:
../_shared/feedback-interfaces.md, the closing reflex for what this run teaches about
this skill, read at Step 3.
Step 1: Resolve what is under review
The plan comes first, because everything else is graded against it:
- The path the user gave.
- Otherwise
docs/planning/SCOPE.md — define-scope's deliverable and
split-epics' primary input. Its siblings SPECS.md and CONVENTIONS.md are
context, never the document that was split; grading epics against them produces
findings the epics were never meant to satisfy.
- Then
docs/PLAN.md, docs/plan.md, plan.md, then the only plausible planning
markdown under docs/ outside docs/planning/ and docs/epics/.
- Several plausible candidates → ask which one before reading further. Reviewing
against the wrong source is a
P0 finding about your own report.
Then the epics: docs/epics/index.md if present, and every
docs/epics/epic-*/EPIC_*.md in full, frontmatter included. When an epic's source
names a heading or file, compare against that section specifically — it is a claim
the epic makes about its own provenance, and a false one is worth catching.
Read for context when present: the docs each epic's ## Context links (typically
docs/planning/SPECS.md and docs/planning/CONVENTIONS.md), plus CLAUDE.md,
AGENTS.md, CONTRIBUTING.md, and .github/ISSUE_TEMPLATE/.
Step 2: What to look for
- Plan coverage — every material goal, constraint, acceptance criterion and
dependency in the plan lands in exactly one epic where it belongs. Constraints are
the ones most often dropped: they belong to no single feature, so they fall between
epics rather than into one.
- No invented scope — epics add no feature, promise, or constraint the plan does
not support, unless flagged as an assumption. Invented scope is worse than missing
scope: it gets built.
- Epic boundaries — each epic is independently shippable and actually epic-sized.
Fragments too small to ship alone should be merged; an epic spanning several phases
should be split, since
create-issues will otherwise inherit the sprawl.
- Ordering and dependencies — epic numbers preserve plan order unless the plan
numbers them itself,
depends_on points at epics that really are prerequisites,
and no cycle makes the set unstartable.
- Faithful carry-over — goal, scope, out-of-scope, acceptance criteria, risks and
plan-wide constraints survive without over-compression. A summarised acceptance
criterion stops being testable.
- Context links — epics reference the planning docs and never copy them, so the
planning bundle stays the single source of truth. These links cross a bundle
boundary, which changes their form —
bundle-interfaces.md specifies which.
- Schema and GitHub linkage — frontmatter fields, and the agreement between
status, gh_issue, milestone and resource, are specified in
pipeline-interfaces.md. A deviation is P2 unless it breaks downstream work.
Step 3: Write the report
Follow the report contract in ../_shared/review-interfaces.md: the path is
docs/reviews/<YYYY-MM-DD>-epics-<subject>.md, where <subject> is what was reviewed
— the plan slug when the whole set was read, the epic slug when one was. The subject
line is # Epic Review Report; Scope names the epic artifacts reviewed, the plan they
were reviewed against, GitHub verification status, and the external model if one ran
the analysis pass.
Then close the run per ../_shared/feedback-interfaces.md — silently, unless this run
turned up something about this skill that clears both its filters. A finding about the
artifacts under review is not that; it belongs in the report.
