---
name: ao-complete
description: "Verify issue completion before marking done. Run evidence-based verification with Gate Function."
category: core
invokes: [ao-state, ao-task, ao-usage]
invoked_by: [ao-implementation]
state_files:
  read: [constitution.md, baseline.md, focus.json, issues/active.jsonl]
  write: [issues/events.jsonl, focus.json]
references: [.ao/reference/completion-gate.md]
---

# Issue Completion Skill

> **Credit**: Verification Gate Function adapted from obra/superpowers by Jesse Vincent (MIT License). See `.agent/ops/references/superpowers-analysis.md` Section 6 and obra/superpowers `skills/verification-before-completion/SKILL.md`.
> **Canonical Reference**: See `.ao/reference/completion-gate.md` for authoritative completion gate documentation.

## Purpose

Evidence-based verification before allowing issues to be marked complete. NO completion claims without fresh verification evidence.

## The Gate Function

**BEFORE claiming any status, follow this 5-step process:**

### 1. IDENTIFY
What command proves this claim?

- For "tests pass": What test command?
- For "lint passes": What lint command?
- For "feature works": What user action or test?

### 2. RUN
Execute the FULL command (fresh, complete).

```bash
# Run the verification command
{command from constitution or user specified}

# Capture full output
# Check exit code
# Count failures if applicable
```

**Requirements:**
- Run complete command (not abbreviated)
- Use fresh execution (not cached results)
- Capture FULL output
- Check exit code explicitly

### 3. READ
Full output, check exit code, count failures.

```bash
# Example verification read
exit_code=$?
test_count=$(echo "$output" | grep -c "test")
pass_count=$(echo "$output" | grep -c "PASSED")
fail_count=$(echo "$output" | grep -c "FAILED")

echo "Exit code: $exit_code"
echo "Tests: $test_count, Passed: $pass_count, Failed: $fail_count"
```

**What to read:**
- Full command output (not just summary)
- Exit code (0 = success, non-zero = failure)
- Test/framework output
- Linting output
- Build output

### 4. VERIFY
Does output confirm the claim?

```bash
# Verification decision
if [ $exit_code -eq 0 ] && [ $fail_count -eq 0 ]; then
    echo "✅ VERIFICATION PASSED"
    echo "Claim: 'tests pass' is CONFIRMED"
else
    echo "❌ VERIFICATION FAILED"
    echo "Claim: 'tests pass' is NOT CONFIRMED"
    echo "Exit code: $exit_code, Failures: $fail_count"
fi
```

**Verification Rules:**
- Don't use "should", "probably", "seems to"
- Don't express satisfaction before verification
- Don't trust agent success reports without checking
- Don't rely on partial verification

### 5. ONLY THEN
Make the claim.

**ONLY AFTER all 5 steps complete:**
- Run `ao issue close ISSUE_ID --log "Verified: {summary}" --status done`
- Document verification in issue log

## Verification Requirements by Issue Type

### BUG Fixes

**Verification checklist:**
- [ ] Failing test reproduces the bug (run and see fail)
- [ ] Fix implemented
- [ ] Test passes (run and verify)
- [ ] No regressions (run full test suite)

**Required evidence:**
```
Before fix:
$ {test_command}
❌ FAILED - {bug symptom}

After fix:
$ {test_command}
✅ PASSED - All tests pass
$ {full_test_suite}
✅ NO REGRESSIONS
```

### FEAT Implementation

**Verification checklist:**
- [ ] All acceptance criteria verified
- [ ] Tests pass (run test command, read output)
- [ ] Linting passes (run linter, read output)
- [ ] Build succeeds (run build, verify exit 0)

**Required evidence:**
```
$ {test_command}
✅ PASSED - {N} tests, {coverage}% coverage

$ {lint_command}
✅ PASSED - No lint errors

$ {build_command}
✅ PASSED - Build successful

Acceptance criteria:
- [x] Criterion 1: {verified}
- [x] Criterion 2: {verified}
```

### CHORE / DOCS / REFAC

**Verification checklist:**
- [ ] No test failures introduced
- [ ] No lint errors introduced
- [ ] Acceptance criteria met

## Red Flags to Prevent

| Red Flag | Why Wrong | Correct Approach |
|-----------|-----------|-----------------|
| Using "should" | Speculative, not verified | Run verification command, check output |
| Using "probably" | Uncertain, not evidence | Execute command, check result |
| Using "seems to" | Subjective, not verified | Check exit code, count failures |
| Expressing satisfaction before verification | Unverified claim | Run verification FIRST, then claim |
| Trusting agent reports | Agent can be wrong | Check output, verify exit code |
| Relying on partial verification | Incomplete evidence | Run FULL verification command |

## Procedure

### 1) Read Issue

- Load issue from ao: `ao issue show ISSUE_ID --yes --format json --progress none`
- Check issue type (BUG, FEAT, CHORE, etc.)
- Identify verification requirements for type

### 2) Select Verification Command

From `.agent/ops/constitution.md` or user specification:
- Build command
- Lint command
- Test command

### 3) Run Gate Function

Execute IDENTIFY → RUN → READ → VERIFY → ONLY THEN

### 4) Document Verification

Add to issue notes:
```markdown
### Verification [Date]

**Claim**: {what was claimed}
**Command**: {verification command used}

**Output**:
```
{full command output}
```

**Result**: ✅ VERIFIED / ❌ FAILED

**Exit code**: {exit_code}
**Failures**: {count if any}
```

### 5) Update Issue Status

**If verification PASSED:**
```bash
ao issue close ISSUE_ID \
  --log "Verified: {N} tests pass, coverage {X}%, lint clean" \
  --status done --yes --format json --progress none
```

**If verification FAILED:**
```bash
printf '%s' '{"set":{"status":"blocked"},"append":{"log":[{"ts":"YYYY-MM-DD","text":"Verification failed: {reason}"}]}}' | \
  ao issue patch ISSUE_ID --in - --yes --format json --progress none
```

### 6) Update Focus

Log completion in `.agent/ops/focus.json`:
```markdown
### Just Completed
- {Date}: **{ISSUE-ID}** — {Title} ✅
  - Verification: PASSED
  - Duration: {minutes} minutes
```

## Integration with ao-implementation

This skill is invoked by `ao-implementation` during the completion gate:

```markdown
From ao-implementation:

## Completion Gate (MANDATORY)

Before setting `status: done`:

1. **Run verification against baseline:**
   ```
   invoke ao-complete
   ```

2. **If verification FAILS:**
   - STOP — do not mark done
   - Fix issues, re-run verification

3. **If verification PASSES:**
   - `ao issue close ISSUE_ID --log "Verified" --status done`
   - Update focus.json
```

## Anti-Patterns

| Anti-Pattern | Problem | Better Approach |
|--------------|---------|-----------------|
| Claiming completion without running verification | No evidence | IDENTIFY command, RUN it, READ output, VERIFY, ONLY THEN claim |
| Assuming tests pass because code looks right | Subjective | Run test command, check exit code |
| Trusting build succeeded without checking | Could fail | Run build, verify exit code is 0 |
| Partial verification (some tests, not all) | Incomplete | Run FULL test suite |
| Cached results | Not fresh | Run verification command fresh every time |

## Verification Templates

Use templates in `.ao/skills/ao-complete/templates/`:
- `BUG-verification.md` - For bug fixes
- `FEAT-verification.md` - For feature implementation

These provide structured verification checklists by issue type.
