bug-start

Bug Start

Table of Contents

• Command
• Prerequisites
• Process Overview
• Agents Used
• State Flow
• Outputs
• Error Handling
• Reference

Start the complete bug/feature workflow pipeline - from Bugzilla scraping to validated plan.

Command

/bug-start <bug_id> - Start workflow for a Bugzilla bug or feature request

Accepts:

• 6231 - Just the bug number
• bug/6231 - Branch format
• Full URL from project config bugzilla.baseUrl - e.g. <bugzilla.baseUrl>/show_bug.cgi?id=6231
• bug-6231 - Hyphenated format

Prerequisites

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.

• Bugzilla accessible at the URL read from project config bugzilla.baseUrl
• No existing workflow for this bug (check state file first)

---

Process Overview

1. Ingest: Normalize input → Acquire lock → Scout Bugzilla → Create dossier → Git branch
2. Analyze: Determine FE/BE/MIXED/FEATURE verdict
3. Plan: Based on verdict, generate implementation plan or feature design
4. TEST_SPEC (MANDATORY): Generate test specification for verification
5. Validate: Validate plan quality (score >= 70)
6. Notify: Send Slack notification (WORKFLOW_STARTED)
7. STOP: Display plan for user approval

Then user runs /bug-accept <bugId> to execute.

See INGEST.md for detailed ingest steps.

---

CRITICAL: Scout Agent Invocation

When spawning the bugzilla-scout agent, you MUST use this exact pattern:

Task({
  description: "Scrape Bugzilla bug data",
  prompt: "Read and execute ${CLAUDE_PLUGIN_ROOT}/infrastructure/agents/bugzilla-scout.md to scrape bug <bugId> from <bugzilla.baseUrl>/show_bug.cgi?id=<bugId>",
  subagent_type: "general-purpose",
  model: "opus"
})

WARNING: Do NOT use subagent_type: "bugzilla-scout". While this gives Playwright tool access, it does NOT load the agent instructions from the .md file. Without instructions, the agent won't know to call browser_navigate or browser_snapshot, resulting in hallucinated data with 0 tool calls.

Why general-purpose? It has access to the Read tool, so the agent can read its own instruction file before executing.

---

MANDATORY: Scout Result Verification

After receiving results from the scout agent, you MUST verify the data before proceeding:

Anti-Hallucination Gate (CHECK FIRST)

Before parsing any JSON, check the raw scout output for evidence of real tool execution:

1. Snapshot excerpt present: Output MUST contain [RAW SNAPSHOT EXCERPT with actual page content
2. Bug ID in excerpt: The excerpt MUST contain Bug {bugId} or id={bugId}
3. Real tool evidence: Output should show actual <function_results> blocks, not just <function_calls>

If ANY of these fail → STOP immediately:

Error: Scout hallucinated / no tool evidence

The scout agent did not provide evidence of real MCP tool execution.
- Missing raw snapshot excerpt, OR
- Bug ID not found in excerpt, OR
- No function_results blocks (only simulated calls)

This bug's data cannot be trusted. Please:
1. Run /bug-reset {bugId}
2. Try /bug-start {bugId} again
3. If it fails again, manually verify at: <bugzilla.baseUrl>/show_bug.cgi?id={bugId}

DO NOT proceed to JSON parsing if the gate fails.

---

Verification Steps (after gate passes)

1. Parse the returned JSON from the scout agent
2. Check Bug ID Match: Verify scoutResult.id === requestedBugId
3. Check Valid Title: Verify scoutResult.title is not null/empty and has at least 3 characters
4. Check Success Flag: Verify scoutResult.success === true

If Verification Fails

If ANY check fails:

1. Log error with details:

   Scout verification failed for bug {bugId}:
   - Requested: {requestedBugId}
   - Received: {scoutResult.id || 'null'}
   - Title: {scoutResult.title || 'empty'}
   - Error: {scoutResult.error || 'none'}
   

2. DO NOT proceed with workflow - do not create dossier or continue

3. Report to user:

   Error: Scout returned invalid data for bug {bugId}
   
   The scout agent may have hallucinated data. Please verify:
   1. Bug exists at <bugzilla.baseUrl>/show_bug.cgi?id={bugId}
   2. Try running /bug-reset {bugId} and /bug-start {bugId} again
   
   Details: {verification failure reason}
   

4. If first attempt, retry ONCE with fresh browser state (the scout agent's Step 0.5 handles this)

Verification Code Reference

// Pseudo-code for verification logic
function verifyScoutResult(scoutResult, requestedBugId) {
  if (!scoutResult.success) {
    throw new Error(`ScoutFailed: ${scoutResult.error || 'Unknown error'}`);
  }

  if (scoutResult.id !== requestedBugId) {
    throw new Error(`BugIdMismatch: Requested ${requestedBugId} but got ${scoutResult.id}`);
  }

  if (!scoutResult.title || scoutResult.title.length < 3) {
    throw new Error(`InvalidTitle: Scout returned empty or invalid title`);
  }

  return true; // Verification passed
}

---

Agents Used

Agent	Purpose
bugzilla-scout.md (via general-purpose)	Scrape bug data from Bugzilla
bug-dossier-writer	Create dossier and state file
analysis	Determine FE/BE/MIXED/FEATURE verdict
fe-implementer-planner	Generate minimal-risk plan (FE/MIXED)
feature-designer	Design new feature (FEATURE)
test-spec-generator	Generate test specification
plan-validator	Validate plan quality
backend-doc-writer	Create BE handoff doc (BE/MIXED)
slack-notifier	Send WORKFLOW_STARTED notification

---

State Flow

INIT → SCOUT → DOSSIER → ANALYZE → VERDICT
                                      ↓
                            ┌─────────┼─────────────┐
                            ↓         ↓             ↓
                        FE/MIXED    BE          FEATURE
                            ↓         ↓             ↓
                        PLAN_FE   DONE_BE   FEATURE_DESIGN
                            ↓                       ↓
                            └──────→ TEST_SPEC ←───┘
                                        ↓
                                    VALIDATE
                                        ↓
                          (user approval via /bug-accept)
                                        ↓
                                    EXECUTE → VERIFY → CLOSED

CRITICAL: TEST_SPEC state is MANDATORY for all FE, MIXED, and FEATURE verdicts. The workflow MUST NOT proceed to VALIDATE without a valid testSpec in the state file.

---

Outputs

Output	Path
Dossier	<paths.dossierDir> from project config (default: docs/bugflow)/bug-<bugId>.md
State	<paths.stateDir> from project config (default: .bugflow)/<bugId>.json
Backend Doc	<paths.dossierDir>/bug-<bugId>-backend-doc.md (BE/MIXED only)
Logs	<paths.stateDir>/_logs/<bugId>.log.json

Error Handling

Bugzilla Not Accessible

Error: Cannot access Bugzilla at <bugzilla.baseUrl>

Possible causes:
- VPN not connected
- Bugzilla server down
- Network issue

Please check connectivity and try again.

Bug Not Found

Error: Bug <bugId> not found in Bugzilla

Verify the bug ID is correct: <bugzilla.baseUrl>/show_bug.cgi?id=<bugId>

Workflow Already Exists

Workflow already exists for bug <bugId>

Current state: <state>
Branch: <branch>

Use `/bug-status <bugId>` to check progress.
Use `/bug-reset <bugId>` to start over.

---

Reference

• INGEST.md - Read for detailed Scout/Dossier/Branch steps and deadline management
• ANALYSIS.md - Read for verdict logic, criteria, and analysis agent context

---

MANDATORY: Test Specification Generation

After planning completes (PLAN_FE or FEATURE_DESIGN), ALWAYS spawn test-spec-generator before proceeding to VALIDATE.

For Bug Fixes (FE/MIXED verdicts):

Task({
  description: "Generate test specification",
  prompt: "Read and execute ${CLAUDE_PLUGIN_ROOT}/infrastructure/agents/test-spec-generator.md for bug <bugId>.
           State file: <paths.stateDir>/<bugId>.json
           Use planResult from state file to create verification assertions.",
  subagent_type: "general-purpose",
  model: "sonnet"
})

For Features (FEATURE verdict):

Task({
  description: "Generate test specification",
  prompt: "Read and execute ${CLAUDE_PLUGIN_ROOT}/infrastructure/agents/test-spec-generator.md for bug <bugId>.
           State file: <paths.stateDir>/<bugId>.json
           Use featureDesignResult from state file.
           Convert featureSpec.testCases to structured assertions.",
  subagent_type: "general-purpose",
  model: "sonnet"
})

After Completion:

1. Verify testSpec exists: State file MUST have testSpec field with non-empty assertions array
2. Update state: Transition to TEST_SPEC state
3. If test-spec-generator fails: STOP and report error - do NOT proceed to VALIDATE

// Verification after test-spec-generator completes
const state = await readState(bugId);

if (!state.testSpec || !state.testSpec.assertions?.length) {
  // HALT - Cannot proceed without testSpec
  return {
    error: "Test specification generation failed",
    action: "RETRY_TEST_SPEC",
    message: "testSpec is required for verification. Run test-spec-generator again."
  };
}

// Update state to TEST_SPEC
await updateState(bugId, { state: 'TEST_SPEC' });

CRITICAL: Do NOT proceed to VALIDATE without a valid testSpec. This ensures the /bug-accept phase can run automated verification.

---

MANDATORY: Slack Notification

After plan validation passes, ALWAYS send Slack notification with full plan details before stopping for approval.

Building the Notification Message

Read the state file and extract plan details based on verdict:

// Read state file
const state = await readState(bugId);

// Build planDetails based on verdict
let planDetails;

if (state.analysisResult.verdict === 'FEATURE') {
  // FEATURE verdict - use featureDesignResult
  const fdr = state.featureDesignResult || {};
  planDetails = {
    strategy: 'feature_implementation',
    riskLevel: fdr.riskLevel || 'medium',
    touchpoints: (fdr.touchpoints || []).slice(0, 10),
    changes: (fdr.components || []).map(c => `Implement ${c.name}: ${c.description || ''}`.substring(0, 100))
  };
} else {
  // FE/MIXED verdict - use planResult
  const pr = state.planResult || {};
  const touchpoints = (pr.touchpoints || [])
    .slice(0, 10)
    .map(t => `${t.file}:${t.startLine || '?'}-${t.endLine || '?'}`);

  const changes = [
    ...(pr.modifiedFunctions || []).map(f => `Modify ${f.name}(): ${f.description || ''}`),
    ...(pr.newFunctions || []).map(f => `Add ${f.name}(): ${f.description || ''}`)
  ].map(c => c.substring(0, 100)); // Truncate long descriptions

  planDetails = {
    strategy: pr.strategy || 'minimal_fix',
    riskLevel: pr.riskLevel || 'low',
    touchpoints: touchpoints,
    changes: changes
  };
}

Format Touchpoints and Changes

function formatTouchpointsList(touchpoints, totalCount) {
  if (!touchpoints.length) return '• (none)';
  let lines = touchpoints.map(t => `• \`${t}\``);
  if (totalCount > touchpoints.length) {
    lines.push(`• _...and ${totalCount - touchpoints.length} more files_`);
  }
  return lines.join('\n');
}

function formatChangesList(changes) {
  if (!changes.length) return '• (none)';
  return changes.map(c => `• ${c}`).join('\n');
}

Send the Notification

mcp__slack__slack_post_message({
  channel_id: "read from project config `slack.channelId`",
  text: `:bug: *Bug ${bugId} Workflow Started*

*Title:* ${title}
*Branch:* \`${branch}\`
*Verdict:* *${verdict}* (${confidence} confidence)

:clipboard: *Implementation Plan*
*Strategy:* ${planDetails.strategy}
*Risk Level:* ${planDetails.riskLevel}

*Files to Modify:*
${formatTouchpointsList(planDetails.touchpoints, totalTouchpointCount)}

*Changes:*
${formatChangesList(planDetails.changes)}

:page_facing_up: Dossier: \`<paths.dossierDir>/bug-${bugId}.md\`
:arrow_right: Run \`/bug-accept ${bugId}\` to execute`
})

Handling BE Verdict

For BE (Backend) verdict, the plan details are NOT included since no FE implementation is planned:

mcp__slack__slack_post_message({
  channel_id: "read from project config `slack.channelId`",
  text: `:wrench: *Bug ${bugId}: Backend Issue Detected*

*Verdict:* *BE* (Backend)
*Title:* ${title}

Backend analysis doc ready:
\`<paths.dossierDir>/bug-${bugId}-backend-doc.md\`

Please review and forward to backend team.`
})

Fallback for Missing Plan Data

If plan details are not available (planResult/featureDesignResult missing), fall back to minimal message:

if (!planDetails || !planDetails.touchpoints?.length) {
  // Fallback - send minimal notification
  text = `:bug: *Bug ${bugId} Workflow Started*

*Title:* ${title}
*Branch:* \`${branch}\`
*Verdict:* *${verdict}*

:page_facing_up: Dossier: \`<paths.dossierDir>/bug-${bugId}.md\`
:arrow_right: Run \`/bug-accept ${bugId}\` to execute`;
}

CRITICAL: This notification must be sent before displaying the plan to the user. Failures are logged but don't block workflow.

---

MANDATORY: Final Output Format

After validation passes and Slack notification is sent, you MUST display this exact output format:

═══════════════════════════════════════════════════════════════════════
WORKFLOW PAUSED — AWAITING USER APPROVAL
═══════════════════════════════════════════════════════════════════════

Bug {bugId}: {title}
Branch: {branch}
Verdict: {verdict}

Plan ready for review in: <paths.dossierDir>/bug-{bugId}.md

DO NOT IMPLEMENT — Run /bug-accept {bugId} to execute

Other commands:
  /bug-plan {bugId}   - Regenerate the plan
  /bug-status {bugId} - Check workflow state
  /bug-reset {bugId}  - Start over

═══════════════════════════════════════════════════════════════════════

CRITICAL RULES:

1. DO NOT display the full plan inline — Only show the file path. Displaying the plan text inline causes Claude to treat it as an instruction to execute.

2. The stop banner is mandatory — It serves as a visual "stop sign" that prevents premature implementation.

3. Never say "Implement the following plan" — This phrase triggers implementation. Instead, say "Plan ready for review".

Why this works: By NOT displaying the full plan inline, and instead pointing to the dossier file, we avoid Claude (or a resumed session) treating the plan as an actionable instruction.