bug-verify

Skill: bug-verify

Configuration Required: This skill requires project configuration. If .claude/bugflow/config/environment.json does not exist, prompt the user to run /bugflow:bug-setup first.

Table of Contents

• Metadata
• Description
• V3 Integration Points
• Prerequisites
• Execution Flow
  • Step 1: Validate State
  • Step 1.5: Verify/Update Workflow Lock (V3)
  • Step 2: Read Test Plan
  • Step 3: Generate Verification Checklist
  • Step 4: Spawn Verifier Subagent (Optional)
  • Step 5: Update Dossier
  • Step 6: Update State
  • Step 6.5: Log Verification Events (V3)
  • Step 7: Return Results
  • Step 8: Send Slack Notification
• Verification Matrix
• Error Handling

Metadata

• Command: /bug-verify <bug_id>
• Aliases: bug verify, bugverify
• Args: bug_id (required) - Bugzilla bug ID

Description

Runs verification tests to confirm the bug fix works.

V3 Integration Points

This command integrates with the following V3 systems:

System	Reference	Purpose
Workflow Lock	${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/workflow-lock.md	Prevent duplicate workflows
Atomic State IO	${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/state-io.md	Safe state read/write
Structured Logging	${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/logger.md	Event tracking
Context Filtering	${CLAUDE_PLUGIN_ROOT}/infrastructure/context-specs.json	Token optimization

All state writes MUST use atomic protocol. All agent spawns MUST log AGENT_START/AGENT_COMPLETE. All phase transitions MUST log STATE_CHANGE.

Prerequisites

• Changes must be applied (/bug-accept completed)
• State must be EXECUTE

---

Execution Flow

Step 1: Validate State

Read <paths.stateDir> from project config (default: .bugflow)/.json`:

Step 1.5: Verify/Update Workflow Lock (V3)

See: ${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/workflow-lock.md for full implementation.

Steps:

1. Check if <paths.stateDir> from project config (default: .bugflow)/.lock` exists
2. If exists:
   • Read lock file
   • Verify sessionId matches current workflow (from state file)
   • Update phase to "VERIFY"
   • Extend expiresAt by 4 hours (reset timeout)
3. If NOT exists:
   • Log LOCK_STALE event
   • Create new lock with current session

Lock Update Content:

{
  "bugId": "<bugId>",
  "acquiredAt": "<original acquiredAt>",
  "sessionId": "<existing or new sessionId>",
  "phase": "VERIFY",
  "expiresAt": "<ISO timestamp + 4 hours from now>"
}

Log Event: LOCK_UPDATE with phase transition

{
  "event": "LOCK_UPDATE",
  "bugId": "<bugId>",
  "details": {
    "previous_phase": "<previous phase>",
    "new_phase": "VERIFY",
    "expires_at": "<new expiry>"
  }
}

If state < EXECUTE:

Bug <bugId> changes not yet applied.
Run `/bug-accept <bugId>` first.

If state >= VERIFY:

Bug <bugId> already verified.
State: <state>
Ready to commit and create PR.

Step 2: Read Test Plan

From state file and dossier:

• Manual test steps
• Playwright test specs
• Regression areas
• Acceptance criteria

Step 3: Generate Verification Checklist

## Verification Checklist for Bug <bugId>

### Original Repro Steps
[ ] 1. <repro step 1>
[ ] 2. <repro step 2>
[ ] 3. <repro step 3>

Expected: Bug should NOT reproduce anymore

### Acceptance Criteria
[ ] <criterion 1>
[ ] <criterion 2>

### Regression Checks
[ ] <regression area 1> - Still works
[ ] <regression area 2> - Still works

Step 4: Spawn Verifier Subagent (Optional)

If Playwright tests are specified, use the verifier agent to run verification tests.

Provide context:

• bugId: <bugId>
• testPlan: from state file
• appUrl: read from project config app.developmentUrl

Expected output:

{
  "automated": {
    "ran": true,
    "passed": true,
    "results": [...]
  },
  "screenshots": [
    "verify-<bugId>-before.png",
    "verify-<bugId>-after.png"
  ]
}

Step 5: Update Dossier

Write to VERIFICATION section:

• Repro matrix (before/after)
• Test results
• Evidence (screenshots, logs)

Step 6: Update State

{
  "state": "VERIFY",
  "verificationResult": { /* Verifier output */ },
  "executionLog": [
    ...existing,
    { "timestamp": "<ISO>", "action": "VERIFY", "result": "success" }
  ]
}

Step 6.5: Log Verification Events (V3)

See: ${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/logger.md for full logging utilities.

Log verification start:

{
  "timestamp": "{{ISO}}",
  "workflowId": "{{workflowId}}",
  "bugId": "{{bugId}}",
  "event": "AGENT_START",
  "agent": "verifier",
  "phase": "VERIFY",
  "details": { "test_count": {{testSpec.assertions.length}} }
}

Log verification result (on complete):

{
  "timestamp": "{{ISO}}",
  "workflowId": "{{workflowId}}",
  "bugId": "{{bugId}}",
  "event": "AGENT_COMPLETE",
  "agent": "verifier",
  "phase": "VERIFY",
  "duration_ms": {{durationMs}},
  "outcome": "success" | "failure",
  "details": {
    "assertions_passed": {{passedCount}},
    "assertions_failed": {{failedCount}},
    "screenshots_captured": {{screenshotCount}}
  }
}

If verification fails, also log:

{
  "timestamp": "{{ISO}}",
  "workflowId": "{{workflowId}}",
  "bugId": "{{bugId}}",
  "event": "VALIDATION_FAIL",
  "phase": "VERIFY",
  "details": {
    "failed_assertions": {{failedAssertions}},
    "attempt_number": {{attemptNumber}}
  }
}

Append to log file: <paths.stateDir> from project config (default: .bugflow)/_logs/.log.json`

Step 7: Return Results

Bug <bugId>: Verification Complete

Manual Checklist:
[ ] Original repro steps no longer reproduce bug
[ ] <acceptance criterion 1>
[ ] <acceptance criterion 2>
[ ] Regression areas still work

<If automated tests ran>
Automated Tests: PASSED
Screenshots saved to docs/bugflow/assets/bug-<bugId>/

Dossier updated: <paths.dossierDir> from project config/bug-<bugId>.md

Next:
- Complete manual verification checklist
- Commit changes
- Create PR for branch: bug/<bugId>-<slug>

Step 8: Send Slack Notification

After verification completes, notify Slack channel read from project config slack.channelName (read from project config slack.channelId).

---

Verification Matrix

| Step | Before Fix | After Fix | Status |
|------|-----------|-----------|--------|
| Repro step 1 | Bug present | Fixed | PASS |
| Repro step 2 | Error shown | Works | PASS |
| Regression A | Working | Working | PASS |

---

Error Handling

Changes Not Applied

Bug <bugId> changes not yet applied.
Run `/bug-accept <bugId>` first.

App Not Running

Cannot verify: Application not accessible at read from project config `app.developmentUrl`
Start the application server and try again.

Test Failure

Verification FAILED for bug <bugId>

Failed check: <check_name>
Expected: <expected>
Actual: <actual>

The fix may be incomplete. Review and update the plan.