acceptance-verification

name	acceptance-verification
description	Verify GitHub issue acceptance criteria against codebase evidence. Posts structured verification comments on issues.
user-invocable	true
allowed-tools	Bash, Read, Grep, Glob
argument-hint	Issue number to verify
catalog_description	Verify GitHub issue acceptance criteria against codebase evidence.

Acceptance Verification — Issue Criteria Checker

Verify whether acceptance criteria defined in a GitHub issue have been met, partially met, or remain open. Posts a structured verification comment on the issue with evidence.

Configuration

Variable	Description	Example
{{CC_GITHUB_OWNER}}	Repository owner	myorg
{{CC_GITHUB_REPO}}	Repository name	my-project
{{CC_PROJECT_NUMBER}}	GitHub Project number	3
{{CC_PROJECT_ID}}	GitHub Project node ID	PVT_kwHOA5GKMc4BPDsB
{{CC_STATUS_DONE_ID}}	"Done" column option ID	52a13056
{{CC_STATUS_FIELD_ID}}	Status field ID	PVTSSF_...

Workflow

When invoked with an issue number:

Step 1: Extract Acceptance Criteria

gh issue view <number> --repo {{CC_GITHUB_OWNER}}/{{CC_GITHUB_REPO}} --json title,body,labels,state,comments

Parse the issue body for acceptance criteria. Look for:

• Checkbox lists: - [ ] criteria or - [x] criteria
• Numbered lists under headers like "Acceptance Criteria", "Requirements", "Definition of Done"
• Bullet points under "Success Criteria" or "Verification"

Extract each criterion as a separate item. If no structured criteria found, extract key requirements from the issue description.

Step 2: Gather Evidence

For each criterion, search for evidence across these sources:

a) Git history — commits referencing the issue:

gh api repos/{{CC_GITHUB_OWNER}}/{{CC_GITHUB_REPO}}/commits --jq '.[].commit.message' -X GET -f sha=development -f per_page=50 | grep -i "#<number>"
git log --oneline --all --grep="<keyword>" | head -10

b) Code changes — files modified for this issue (use Grep and Glob tools)

c) Test coverage — tests verifying the criterion (search test directories)

d) Documentation — docs addressing the criterion

e) CI/CD pipeline — workflow changes if applicable

Step 3: Assess Each Criterion

Status	Symbol	Meaning
PASS	:white_check_mark:	Criterion fully satisfied with evidence
PARTIAL	:large_orange_diamond:	Some aspects met, gaps remain
FAIL	:x:	No evidence of implementation
N/A	:heavy_minus_sign:	Criterion not applicable or deferred

Step 4: Post Verification Comment

gh issue comment <number> --repo {{CC_GITHUB_OWNER}}/{{CC_GITHUB_REPO}} --body "$(cat <<'COMMENT'
## Acceptance Criteria Verification

**Verified by**: Claude Code — Acceptance Verification
**Date**: $(date +%Y-%m-%d)
**Branch**: development

### Results

| # | Criterion | Status | Evidence |
|---|-----------|--------|----------|
| 1 | <criterion text> | :white_check_mark: PASS | <evidence summary> |
| 2 | <criterion text> | :large_orange_diamond: PARTIAL | <what's done, what's missing> |
| 3 | <criterion text> | :x: FAIL | No implementation found |

### Summary

- **Total criteria**: N
- **Passed**: X / **Partial**: Y / **Failed**: Z
- **Overall**: PASS / PARTIAL / FAIL

### Evidence Details

#### Criterion 1: <text>
- **Commits**: `abc1234` — <commit message>
- **Files**: `path/to/file:42` — <relevant code>
- **Tests**: `t/path/to/test.t` — <test description>

### Recommendation

<If gaps exist: specific actions needed>
<If all pass: ready to move to Done>
COMMENT
)"

Step 5: Auto-tick Checkboxes in Issue Body

For each criterion that received PASS status, update the issue body to check its checkbox (- [ ] → - [x]). Criteria with PARTIAL, FAIL, or N/A remain unchecked.

1. Fetch the current issue body:

BODY=$(gh issue view <number> --repo {{CC_GITHUB_OWNER}}/{{CC_GITHUB_REPO}} --json body --jq '.body')

2. For each PASS criterion, find its matching checkbox line and replace - [ ] with - [x]. Match by searching for a unique substring of the criterion text (first 30+ chars).

3. Update the issue body:

gh issue edit <number> --repo {{CC_GITHUB_OWNER}}/{{CC_GITHUB_REPO}} --body "$UPDATED_BODY"

Rules:

• Only tick boxes for criteria that are PASS — never auto-tick PARTIAL or FAIL
• If a checkbox is already ticked (- [x]), leave it unchanged
• If the issue body has no checkboxes, skip this step
• In --dry-run mode, show which boxes would be ticked but don't update

Step 6: Closure Guard — CRITICAL

NEVER close or suggest closing an issue unless ALL acceptance criteria are PASS.

This is a hard rule with no exceptions:

• If ANY criterion is PARTIAL or FAIL, the issue MUST remain open
• The verification comment MUST explicitly list what remains to be done
• Do NOT tick checkboxes for PARTIAL or FAIL criteria
• Do NOT suggest moving to "Done" if any gaps exist
• When called by other skills/agents (e.g., /issues close, project coordinator), BLOCK the close operation and return the gap list

Only when ALL criteria are PASS:

• If --strict is NOT set: suggest moving the issue to "Done" on the project board, ask user for confirmation before executing
• If --strict IS set: report only, no board changes

Rationale: Premature closure hides unfinished work. It is always better to leave an issue open with clear gap documentation than to close it optimistically.

Options

Flag	Effect
--strict	Report only, no board status changes suggested
--dry-run	Show what would be posted without actually commenting
--quiet	Minimal output, just the summary table

Evidence Search Strategy

Priority order for finding evidence:

1. Explicit references: #<issue-number> in commit messages, PR titles
2. Keyword matching: Key terms from criterion text in code, tests, docs
3. File path inference: If criterion mentions specific component, check that directory
4. Temporal proximity: Recent commits around issue creation/assignment date
5. Test naming: Test descriptions matching criterion intent

Multiple Issues

/verify 19 21 37

Process each issue sequentially and post individual comments.

Epic-Aware Verification

When verifying an issue that contains a task list with sub-issue references (- [ ] #N), this skill detects it as an epic and performs recursive verification:

1. Extract all #N references from task list items in the issue body
2. Run verification on each referenced sub-issue
3. Aggregate sub-issue results into the epic verification comment
4. Verify the epic's own acceptance criteria
5. An epic is PASS only when ALL sub-issues are PASS AND all epic criteria are PASS

This ensures that closing an epic requires complete verification of the entire work tree, not just the parent issue.

Integration

This skill can be invoked by:

• Users directly via /verify <number>
• The project coordinator agent during sprint reviews
• The code standards reviewer agent after code review
• The /project-board verify command (which delegates here)
• Epic verification (recursive — verifies all sub-issues first)