bug-accept

Bug Accept

Table of Contents

• Command
• Prerequisites
• Process Overview
• Agents Used
• State Flow
• Outputs
• Safety Features
• Reference

Execute approved implementation plan with transactional safety and automatic rollback.

Command

/bug-accept <bug_id> - Execute the approved plan for the specified bug

Optional Flags:

• --skip-verify - Skip Playwright verification (use with caution, see below)

Prerequisites

• Plan must exist (from /bug-start auto-plan or manual /bug-plan)
• State must be: PLAN_FE, VALIDATE, FEATURE_DESIGN, TEST_SPEC, or AWAITING_APPROVAL
• testSpec MUST exist (unless using --skip-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.

---

Process Overview

1. Validate - Confirm state is ready for acceptance
2. Verification Gate - Check testSpec exists (MANDATORY)
3. Pre-flight - Check prerequisites (branch, files, no conflicts)
4. Execute - Apply code changes with checkpoint creation
5. Verify - Run Playwright tests against testSpec
6. Notify - MANDATORY: Send parallel Slack + Bugzilla notifications (see below)
7. Report - Display results and next steps (commit + PR)

On failure: Automatic rollback to checkpoint. See ERRORS.md for handling.

---

Verification Gate (MANDATORY - Before Execution)

BEFORE spawning exec-supervisor, validate that testSpec exists:

Step 1: Read State File

const state = await readState(bugId);

Step 2: Check testSpec

const hasTestSpec = state.testSpec !== null &&
                    state.testSpec !== undefined &&
                    Array.isArray(state.testSpec.assertions) &&
                    state.testSpec.assertions.length > 0;

Step 3: Handle Missing testSpec

If testSpec is missing (and NOT using --skip-verify):

Error: Cannot execute - no test specification exists.

Bug <bugId> is missing testSpec. This is required for automated verification.

Options:
1. Run `/bug-plan <bugId>` to regenerate plan with testSpec
2. Run test-spec-generator manually:
   Task({
     subagent_type: "general-purpose",
     prompt: "Read and execute .claude/agents/test-spec-generator.md for bug <bugId>"
   })
3. Run `/bug-accept <bugId> --skip-verify` to proceed without verification (NOT RECOMMENDED)

CRITICAL: Do NOT proceed with execution if testSpec is missing. The workflow must halt until the user either:

• Generates a testSpec
• Explicitly opts to skip verification

---

Skip Verification Flag (Use with Caution)

/bug-accept <bugId> --skip-verify - Execute without running Playwright verifier

When to Use

• Trivial changes (typo fixes, comment updates)
• Manual testing already completed outside workflow
• Verifier infrastructure unavailable (Playwright issues)
• Time-sensitive deployments after manual QA

MANDATORY When Skipping

1. User Acknowledgment Required - Ask user to confirm they're skipping verification:

AskUserQuestion({
  questions: [{
    question: "Skip automated verification? This means no Playwright tests will run.",
    header: "Skip Verify",
    options: [
      { label: "Skip verification", description: "Proceed without automated tests (you've done manual testing)" },
      { label: "Cancel", description: "Don't proceed - I need to generate testSpec first" }
    ],
    multiSelect: false
  }]
})

2. State File MUST Record Skip:

{
  "verificationResult": {
    "status": "skipped",
    "reason": "UserChoice",
    "acknowledgedBy": "user",
    "timestamp": "<ISO>"
  }
}

3. Slack Notification MUST Say:

*Verification:* SKIPPED (User choice)

4. Bugzilla Comment MUST Note:

Verification: Skipped by user request

---

Agents Used

Agent	Purpose
pre-flight	Validate prerequisites before execution
executor	Apply code changes (prompts for edits)
verifier	Run Playwright tests
slack-notifier	Send CHANGES_APPLIED notification
bugzilla-commenter	Post completion comment

---

State Flow

PLAN_FE/VALIDATE/FEATURE_DESIGN
        ↓
    PRE_FLIGHT
        ↓
      EXECUTE
        ↓
      VERIFY
       / \
   PASS   FAIL → VERIFY_FAIL (rollback)
     ↓
   CLOSED

---

Outputs

Output	Path
Dossier	<paths.dossierDir> from project config (default: docs/bugflow)/bug-<bugId>.md
State	<paths.stateDir> from project config (default: .bugflow)/<bugId>/state.json
Logs	<paths.stateDir> from project config (default: .bugflow)/_logs/<bugId>.log.json
Slack	read from project config slack.channelName
Bugzilla	Fix summary comment

Safety Features

• Pre-flight validation prevents wasted execution
• Checkpoint system enables reliable rollback
• Step-level checkpoints for granular recovery
• Parallel notifications both awaited (not fire-and-forget)
• Cleanup runs in finally block pattern

---

Reference

• EXECUTION.md - Read for detailed step-by-step execution flow and agent context
• ERRORS.md - Read for error handling, rollback procedures, and recovery
• V3-INTEGRATION.md - Read for logging, locking, and state management details

---

MANDATORY: Notifications (Step 5)

After verification passes (or if skipped), send notifications:

1. Slack (Automatic)

mcp__slack__slack_post_message({
  channel_id: "read from project config `slack.channelId`",
  text: "Bug <bugId>: Fix Complete\n\n*Title:* <title>\n*Branch:* `<branch>`\n*Verdict:* *<verdict>*\n\n*Changes:* <N> file(s) modified\n*Verification:* PASSED\n\nDossier: `<paths.dossierDir from project config>/bug-<bugId>.md`\n\nReady for commit + PR"
})

2. Bugzilla (Requires User Approval)

IMPORTANT: Always ask user to approve the Bugzilla comment before posting.

1. Draft the comment and show it to the user:

Proposed Bugzilla comment for bug <bugId>:
---
[FE Fix Applied]

Branch: <branch>
Files modified: <list>

Summary: <brief description of fix>

Ready for commit + PR.
---

2. Use AskUserQuestion to get approval:

AskUserQuestion({
  questions: [{
    question: "Post this comment to Bugzilla?",
    header: "Bugzilla",
    options: [
      { label: "Post comment", description: "Post the comment shown above to Bugzilla" },
      { label: "Skip", description: "Don't post to Bugzilla" }
    ],
    multiSelect: false
  }]
})

3. Only spawn bugzilla-commenter after user approves.

CRITICAL: Slack can be sent automatically, but Bugzilla comments always require explicit user approval.