| name | verify-issue |
| description | Verify GitHub issue acceptance criteria before handoff or PR — fetch issue, map criteria to checks, report pass/fail per criterion. Use when work tracks an issue, before declaring done, or when asked if an issue is satisfied. |
Verify GitHub issue acceptance criteria
Issue-linked work needs three gates:
- Spec sync — body-hash drift check (below); issue remains authoritative,
spec.md is derived reference.
- Issue AC — this skill: each acceptance criterion verified with evidence.
- Repo quality — developer/done-checklist.md + code-review: tests, done gates, policy, smells.
Do not skip (2) or (3) after (1). Do not declare an issue done based on green CI alone if AC were never mapped.
When to use
| Use | Skip |
|---|
User or plan references an issue (#123, issue URL) | Drive-by fix with no issue |
| Before handoff: "is this done?", "verify the issue" | Pure refactor with no AC |
| Before PR when PR fixes/closes an issue | Docs-only typo with obvious scope |
| Parent after multitask merge for issue-scoped feature | Issue has no criteria and user did not ask for verification |
Prerequisites
- Issue number or URL (e.g.
#80, https://github.com/ORG/REPO/issues/80)
- Local branch or diff containing the implementation
gh authenticated for the repo (git-workflow — use gh for GitHub tasks)
Spec drift check (body-hash)
Before AC verification on feat/ work (or when .agents/specs/<N>-*/spec.md exists):
Do not use issue.updatedAt — labels, assignees, comments, and bots change it without scope changes.
gh issue view <N> --json body --jq .body | shasum -a 256
grep '^Source:' .agents/specs/<N>-<slug>/spec.md
Interpretation:
| Condition | Result |
|---|
No spec.md on feat/ branch | DRIFT: spec missing — create spec from issue before handoff |
First 8 chars of current hash ≠ hash in Source: line | DRIFT: re-sync spec from issue — read issue body, update spec/plan/tasks, new body-hash |
| Hashes match | SYNC OK |
On DRIFT: stop and re-sync from issue (issue first, then spec/plan/tasks). Callable MCP drift tool is a follow-up — these commands are the source of truth in PR 2.
Details: specs/README.md.
Workflow (one pass)
1. Fetch the issue
From repo root (gh uses the current repository):
gh issue view <N> --json number,title,body,state,labels,url,closedAt
gh issue view <N> --comments
Find linked PRs (if verifying an existing PR branch):
gh pr list --search "#<N> in:body" --state all --json number,title,url,state,headRefName
gh pr view <PR> --json body,commits,files
Read title + body + relevant comments. Note state (OPEN/CLOSED) but verify AC yourself — do not assume closed means satisfied.
2. Extract acceptance criteria
Pull every testable requirement into a numbered list. Sources, in order:
| Source | How to extract |
|---|
| Acceptance criteria section | Headings: Acceptance criteria, Acceptance Criteria, AC, Done when, Definition of done, Requirements |
| Task lists | Markdown - [ ] / - [x] lines (GitHub task lists) |
| Bug template fields | expected / "What should happen instead" from bug-report.yml |
| Description bullets | Imperative bullets that state observable outcomes |
| Linked docs | Paths or skill links in the issue (e.g. apps-ui/components.md acceptance block) |
Rules:
- One row per criterion — split compound bullets ("add X and Y") into separate rows when they verify independently.
- Mark inferred criteria with
(inferred) when there is no explicit AC section.
- If the issue is vague, list assumptions you are verifying and flag gaps in the report — do not silently invent scope.
3. Map each criterion to verification
For every criterion, pick one primary method and record the planned check:
| Method | When | Example |
|---|
| Test command | Issue mentions tests, behavior, API, hooks | pnpm --dir packages/apps exec vitest run path/to.test.ts |
| Done gate | Merge-ready / policy-level bar | pnpm test:apps-done-gate, pnpm test:api-done-gate |
| Code inspection | Structural rule, no test yet | rg pattern packages/apps/src/…, read named files |
| OpenAPI / contract | REST shape or endpoint | Diff openapi.json; feature test filter |
| Storybook / manual | UI state, a11y, visual | Mock-tier story exists; pnpm dev:ui + steps from issue |
| Docs | README / skill update requested | File exists; section matches AC |
Load domain depth when mapping: testing, api, apps-ui, storybook.
Planning: If work was planned with plan-feature, align chunk done-when / Verify with rows to these criterion IDs. Map AC to the issue, not to spec.md — spec is technical scope reference only.
4. Run checks and collect evidence
Run the mapped commands and inspections. For each criterion record:
- Status:
PASS | FAIL | PARTIAL | BLOCKED | N/A
- Evidence: command output summary, file path, test name, or grep result (one line)
- Gap: what is missing when not
PASS
Then run the package-appropriate rows from done-checklist.md (smells via code-review).
5. Report
Use this template in handoff, PR body (when user asks), or parent agent summary:
## Issue verification — #<N> <title>
**Issue:** <url>
**Branch / PR:** <name or PR url>
**Issue state:** OPEN | CLOSED (verified independently)
### Acceptance criteria
| # | Criterion | Status | Evidence |
|---|-----------|--------|----------|
| 1 | … | PASS | `vitest …` green; `path/file.test.ts` |
| 2 | … | FAIL | missing mock-tier story for `ExportName` |
| 3 | … | PARTIAL | API test passes; UI story not added |
### Inferred / assumed (if any)
- …
### Repo quality gate
- [ ] [done-checklist](../developer/done-checklist.md) commands run for touched packages
- [ ] [smells](../clean-code/smells.md) scan on touched files
### Verdict
`ISSUE_SATISFIED` | `ISSUE_NOT_SATISFIED` | `ISSUE_PARTIAL`
**Blockers:** …
**Follow-ups:** …
Verdict rules:
ISSUE_SATISFIED — every criterion PASS or N/A; no blockers; done-checklist satisfied for scope.ISSUE_PARTIAL — only N/A or documented out-of-scope nits; at least one PARTIAL with user-approved deferral.ISSUE_NOT_SATISFIED — any FAIL or BLOCKED on a required criterion, or done-checklist not run.
Do not close the issue or claim "fixes #N" unless the user asked and verdict is ISSUE_SATISFIED.
Integration with other skills
| Phase | Skill |
|---|
| Issue → spec → plan → tasks | plan-feature + specs/README.md |
| Plan chunks from issue AC | Copy AC into chunk done-when; engineering rows in tasks.md |
| Implement | Domain skills (api, apps-ui, …) |
| Spec sync gate | verify-issue — body-hash drift (this doc) |
| Issue AC gate | verify-issue (this doc) |
| Technical gate | code-review → done-checklist |
| Multitask merge | multitask-verifier for cross-chunk; then verify-issue for the parent issue |
Related
