review-issues

name	review-issues
description	Review create-issues output against its epic (and the plan when useful) — coverage, sizing, ordering, OKF fields, GitHub linkage — and write a prioritized docs/reviews/<date>-issues-<subject>.md. Use when the user asks to audit, QA, or review generated issues.

Review Issues

Audit the issues create-issues produced for one epic. The question to answer: could a developer work these issues in order, one PR each, and finish the epic without being blocked or building something the epic never 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 (issue schema, status lifecycle, GitHub facts) and ../_shared/bundle-interfaces.md (link forms, reserved files, language). Judge against those two files directly; an issue 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 epic comes first, because the issues are graded against it:

• The path, epic number, or title the user gave.
• Otherwise list docs/epics/epic-*/EPIC_*.md and ask which epic to review — there is no safe default when several epics have issues.

Read that EPIC_<n>.md in full, frontmatter and body, then:

• Every issue file under the epic's issues/, and its issues/index.md if present.
• docs/epics/index.md, when cross-epic dependencies matter.
• The docs the epic's ## Context links — typically docs/planning/SPECS.md and docs/planning/CONVENTIONS.md. Sizing, file paths and required tests are only judgeable against the stack and standards decided there.
• The original plan when the epic's source points at it, or when the user asks to compare all the way back. Otherwise the epic is the contract: an issue is not wrong for omitting something the epic itself dropped — that is review-epics' finding, not this one's.

Read for context when present: CLAUDE.md, AGENTS.md, CONTRIBUTING.md, .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md, and any repo doc defining labels, tests, or branch conventions.

Step 2: What to look for

• Epic coverage — every goal, scope item, acceptance criterion and dependency in the epic appears in at least one issue. Acceptance criteria are the ones that go missing: they are easy to summarise away and impossible to verify afterwards.
• No invented scope — no endpoint, test, UI or implementation promise the epic does not support, unless flagged as an assumption. It will get built.
• Right-sized PRs — one issue, one focused, reviewable PR. Split anything heading toward ~1000 changed lines; merge anything too small to ship on its own. Sizing is the finding developers feel first.
• Implementation order — issue numbers and depends_on let someone work top to bottom without hitting a prerequisite that comes later.
• Issue body quality — action-oriented title, and Summary, Scope, Out of scope, Acceptance criteria, Relevant files, Dependencies and PR size concrete enough to act on. "Implement the backend" is a finding, not an issue.
• Project conventions — required tests, linting, labels and templates discovered from the repo and from CONVENTIONS.md / SPECS.md are reflected in the bodies, so the implementer is not left to guess them.
• Schema and GitHub linkage — issue frontmatter fields, issues/index.md, and the agreement between status, gh_issue, resource, milestone, labels and sub-issue relationships are specified in pipeline-interfaces.md. Sub-issue linkage in particular is what makes the epic issue's progress bar honest, so a break there is P2 even when every file looks fine.

Step 3: Write the report

Follow the report contract in ../_shared/review-interfaces.md: the path is docs/reviews/<YYYY-MM-DD>-issues-<subject>.md, where <subject> is the epic whose issues were reviewed (epic-4). The subject line is # Issue Review Report; Scope names the issue artifacts reviewed, the epic (and plan, when read) 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.