33 KiB
33 KiB
description
| description |
|---|
| Regression-test-first bug fixing workflow with smart SpecSwarm/SpecTest integration |
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Goal
Execute regression-test-first bug fixing workflow to ensure bugs are fixed correctly and prevent future regressions.
Key Principles:
- Test First: Write regression test before fixing
- Verify Failure: Confirm test reproduces bug
- Fix: Implement solution
- Verify Success: Confirm test passes
- No Regressions: Validate no new bugs introduced
Coverage: Addresses ~40% of development work (bug fixes)
Smart Integration Detection
Before starting workflow, detect available plugins for enhanced capabilities:
# Get repository root and plugin directory
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
# Check for SpecSwarm (tech stack enforcement)
SPECSWARM_INSTALLED=$(claude plugin list | grep -q "specswarm" && echo "true" || echo "false")
# Check for SpecLabs (experimental features)
SPECLABS_INSTALLED=$(claude plugin list | grep -q "speclabs" && echo "true" || echo "false")
# Check for web project and Chrome DevTools MCP (web debugging enhancement)
if [ -f "$PLUGIN_DIR/lib/web-project-detector.sh" ]; then
source "$PLUGIN_DIR/lib/web-project-detector.sh"
# Determine if Chrome DevTools should be used
if should_use_chrome_devtools "$REPO_ROOT"; then
CHROME_DEVTOOLS_MODE="enabled"
echo "🌐 Web Project Detected: $WEB_FRAMEWORK"
echo "🎯 Chrome DevTools MCP: Available for enhanced browser debugging"
elif is_web_project "$REPO_ROOT"; then
CHROME_DEVTOOLS_MODE="fallback"
echo "🌐 Web Project Detected: $WEB_FRAMEWORK"
echo "📦 Using Playwright fallback (Chrome DevTools MCP not available)"
else
CHROME_DEVTOOLS_MODE="disabled"
# Non-web project - no message needed
fi
else
CHROME_DEVTOOLS_MODE="disabled"
fi
# Configure workflow based on detection
if [ "$SPECLABS_INSTALLED" = "true" ]; then
EXECUTION_MODE="parallel"
ENABLE_HOOKS=true
ENABLE_METRICS=true
echo "🎯 Smart Integration: SpecLabs detected (experimental features enabled)"
elif [ "$SPECSWARM_INSTALLED" = "true" ]; then
EXECUTION_MODE="sequential"
ENABLE_TECH_VALIDATION=true
echo "🎯 Smart Integration: SpecSwarm detected (tech stack enforcement enabled)"
else
EXECUTION_MODE="sequential"
echo "ℹ️ Running in basic mode (install SpecSwarm/SpecTest for enhanced capabilities)"
fi
Pre-Workflow Hook (if SpecTest installed)
if [ "$ENABLE_HOOKS" = "true" ]; then
echo "🎣 Pre-Bugfix Hook"
# Validate prerequisites
echo "✓ Checking repository status..."
git status --porcelain | head -5
# Load tech stack (if SpecSwarm also installed)
if [ "$SPECSWARM_INSTALLED" = "true" ]; then
echo "✓ Loading tech stack: .specswarm/tech-stack.md"
TECH_STACK_EXISTS=$([ -f ".specswarm/tech-stack.md" ] && echo "true" || echo "false")
if [ "$TECH_STACK_EXISTS" = "true" ]; then
echo "✓ Tech stack validation enabled"
fi
fi
# Initialize metrics
WORKFLOW_START_TIME=$(date +%s)
echo "✓ Metrics initialized"
echo ""
fi
Execution Steps
1. Discover Bug Context
# Get repository root
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
# Source features location helper
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
source "$PLUGIN_DIR/lib/features-location.sh"
# Initialize features directory (handles migration if needed)
get_features_dir "$REPO_ROOT"
# Detect branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
# Try to extract feature number from branch name (bugfix/NNN-*)
FEATURE_NUM=$(echo "$CURRENT_BRANCH" | grep -oE 'bugfix/([0-9]{3})' | grep -oE '[0-9]{3}')
# If no feature number in branch, prompt user
if [ -z "$FEATURE_NUM" ]; then
echo "🐛 Bugfix Workflow"
echo ""
echo "No bugfix branch detected. Please provide bug number:"
echo "Example: 042 (for bugfix/042-login-timeout)"
# Wait for user input
read -p "Bug number: " FEATURE_NUM
# Validate
if [ -z "$FEATURE_NUM" ]; then
echo "❌ Error: Bug number required"
exit 1
fi
# Pad to 3 digits
FEATURE_NUM=$(printf "%03d" $FEATURE_NUM)
fi
# Find or create feature directory using helper
if ! find_feature_dir "$FEATURE_NUM" "$REPO_ROOT"; then
echo "⚠️ Feature directory not found for bug ${FEATURE_NUM}"
echo ""
echo "Please provide bug description (kebab-case):"
echo "Example: login-timeout"
read -p "Description: " BUG_DESC
if [ -z "$BUG_DESC" ]; then
echo "❌ Error: Bug description required"
exit 1
fi
FEATURE_DIR="${FEATURES_DIR}/${FEATURE_NUM}-${BUG_DESC}"
mkdir -p "$FEATURE_DIR"
echo "✓ Created: $FEATURE_DIR"
fi
BUGFIX_SPEC="${FEATURE_DIR}/bugfix.md"
REGRESSION_TEST_SPEC="${FEATURE_DIR}/regression-test.md"
TASKS_FILE="${FEATURE_DIR}/tasks.md"
Output to user:
🐛 Bugfix Workflow - Feature ${FEATURE_NUM}
✓ Branch detected: ${CURRENT_BRANCH}
✓ Feature directory: ${FEATURE_DIR}
2. Create Bugfix Specification
If $BUGFIX_SPEC doesn't exist, create it using this template:
# Bug ${FEATURE_NUM}: [Bug Title]
**Status**: Active
**Created**: YYYY-MM-DD
**Priority**: [High/Medium/Low]
**Severity**: [Critical/Major/Minor]
## Symptoms
[What behavior is observed? What's going wrong?]
- Observable symptom 1
- Observable symptom 2
- Observable symptom 3
## Reproduction Steps
1. Step 1 to reproduce
2. Step 2 to reproduce
3. Step 3 to reproduce
**Expected Behavior**: [What should happen?]
**Actual Behavior**: [What actually happens?]
## Root Cause Analysis
**IMPORTANT: Use ultrathinking for deep analysis**
Before documenting the root cause, you MUST:
1. **Ultrathink** - Perform deep, multi-layer analysis
2. Check database configuration (transforms, defaults, constraints)
3. Analyze property access patterns (camelCase vs snake_case mismatches)
4. Examine caching behavior (frontend, backend, browser)
5. Trace data flow from database → backend → frontend
6. Look for cascading bugs (one bug hiding another)
**Root Cause Documentation:**
[What is causing the bug?]
- Component/module affected
- Code location (file:line)
- Logic error or edge case missed
- Conditions required to trigger
- Configuration mismatches (transforms, environment, etc.)
## Impact Assessment
**Affected Users**: [Who is impacted?]
- All users / Specific user role / Edge case users
**Affected Features**: [What features are broken?]
- Feature A: Completely broken
- Feature B: Partially degraded
**Severity Justification**: [Why this priority/severity?]
**Workaround Available**: [Yes/No - if yes, describe]
## Regression Test Requirements
[What test will prove the bug exists and validate the fix?]
1. Test scenario 1
2. Test scenario 2
3. Test scenario 3
**Test Success Criteria**:
- ✅ Test fails before fix (proves bug exists)
- ✅ Test passes after fix (proves bug fixed)
- ✅ No new regressions introduced
## Proposed Solution
[High-level approach to fixing the bug]
**Changes Required**:
- File 1: [what needs to change]
- File 2: [what needs to change]
**Risks**: [Any risks with this fix?]
**Alternative Approaches**: [Other ways to fix? Why not chosen?]
---
## Tech Stack Compliance
[If SpecSwarm installed, validate solution against tech stack]
**Tech Stack File**: .specswarm/tech-stack.md
**Validation Status**: [Pending/Compliant/Non-Compliant]
---
## Metadata
**Workflow**: Bugfix (regression-test-first)
**Created By**: SpecLab Plugin v1.0.0
**Smart Integration**: ${INTEGRATION_MODE}
Populate template by:
- Load user input (if provided in
$ARGUMENTS) - ULTRATHINK - Perform deep root cause analysis:
- Search for error logs, stack traces
- Check database schema configuration (transforms, defaults)
- Analyze property naming patterns (camelCase vs snake_case)
- Check caching behavior (frontend loaders, backend, browser)
- Trace data flow from database through all layers
- Look for multi-layer bugs (frontend + backend + database)
- Check recent commits for related changes
- Review issues/PRs mentioning bug number
- Analyze repository context:
- Identify all affected layers (database, backend, frontend)
- Check for configuration mismatches
- Look for similar bugs that might indicate patterns
- Prompt user for missing critical information:
- Bug title
- Symptoms (what's broken?)
- Reproduction steps
- Priority/severity
Write completed specification to $BUGFIX_SPEC.
Output to user:
📋 Bugfix Specification
✓ Created: ${BUGFIX_SPEC}
✓ Bug documented with symptoms, root cause, impact
2.5. Orchestrator Detection
After creating the bugfix specification, analyze whether this is an orchestration opportunity:
# Load detection library
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
if [ -f "$PLUGIN_DIR/lib/orchestrator-detection.sh" ]; then
source "$PLUGIN_DIR/lib/orchestrator-detection.sh"
echo ""
echo "🔍 Analyzing bugfix complexity..."
echo ""
# Count bugs in specification (look for "### Bug #" headers or symptoms list)
BUG_COUNT=$(grep -cE "^### Bug #|^- Bug [0-9]+" "$BUGFIX_SPEC" 2>/dev/null || echo "1")
# If user input mentions multiple bugs, count them
if [ -n "$ARGUMENTS" ]; then
ARG_BUG_COUNT=$(echo "$ARGUMENTS" | grep -oE "bug" | wc -l)
if [ "$ARG_BUG_COUNT" -gt "$BUG_COUNT" ]; then
BUG_COUNT=$ARG_BUG_COUNT
fi
fi
# Get list of affected files from bugfix spec
AFFECTED_FILES=$(grep -A 20 "^## Proposed Solution" "$BUGFIX_SPEC" | grep -E "^- File |^ - " | sed 's/^- File //' | sed 's/^ - //' | tr '\n' ' ' || echo "")
# If no files found in spec yet, check user input
if [ -z "$AFFECTED_FILES" ] && [ -n "$ARGUMENTS" ]; then
AFFECTED_FILES=$(echo "$ARGUMENTS" | grep -oE "[a-zA-Z0-9/_-]+\.(ts|tsx|js|jsx|py|go|java)" | tr '\n' ' ')
fi
# Build context info based on spec content
CONTEXT_INFO=""
if grep -qiE "log|logging|console" "$BUGFIX_SPEC"; then
CONTEXT_INFO="${CONTEXT_INFO} requires_logging"
fi
if grep -qiE "restart|reload|rebuild" "$BUGFIX_SPEC"; then
CONTEXT_INFO="${CONTEXT_INFO} requires_server_restarts"
fi
# Check if orchestrator should be used
DETECTION_RESULT=$(should_use_orchestrator "$BUG_COUNT" "$AFFECTED_FILES" "$CONTEXT_INFO" 2>/dev/null)
if [ $? -eq 0 ]; then
echo "🎯 Orchestrator Detection"
echo "========================"
echo ""
# Extract recommendation details
RECOMMENDATION=$(echo "$DETECTION_RESULT" | grep -o '"recommendation": "[^"]*"' | cut -d'"' -f4)
REASON=$(echo "$DETECTION_RESULT" | grep -o '"reason": "[^"]*"' | cut -d'"' -f4)
CONFIDENCE=$(echo "$DETECTION_RESULT" | grep -o '"confidence": "[^"]*"' | cut -d'"' -f4)
echo "Reason: $REASON"
echo "Confidence: $CONFIDENCE"
echo ""
if [ "$RECOMMENDATION" = "orchestrator" ]; then
echo "💡 STRONG RECOMMENDATION: Use Project Orchestrator"
echo ""
echo "This is a textbook orchestration case!"
echo ""
echo "Benefits:"
echo " • Estimated time savings: 40-60%"
echo " • Parallel bug investigation"
echo " • Better context management"
echo " • Coordinated server restarts"
echo " • Specialized agents per domain"
echo ""
echo "Detected signals:"
echo " - $BUG_COUNT bug(s) to fix"
if [ -n "$AFFECTED_FILES" ]; then
DOMAIN_NAMES=$(get_domain_names "$AFFECTED_FILES" 2>/dev/null)
if [ -n "$DOMAIN_NAMES" ]; then
echo " - Spans domains: $DOMAIN_NAMES"
fi
fi
if echo "$CONTEXT_INFO" | grep -q "requires_logging"; then
echo " - Requires extensive logging"
fi
if echo "$CONTEXT_INFO" | grep -q "requires_server_restarts"; then
echo " - Requires server restarts"
fi
echo ""
echo "Choose workflow:"
echo " 1. Continue with sequential bugfix (traditional)"
echo " 2. Switch to Orchestrator debug mode (recommended)"
echo ""
read -p "Your choice (1 or 2): " WORKFLOW_CHOICE
if [ "$WORKFLOW_CHOICE" = "2" ]; then
echo ""
echo "✅ Switching to Orchestrator debug mode..."
echo ""
echo "Next step: Create debug workflow specification"
echo ""
echo "Run one of these commands:"
echo " • /debug:coordinate \"$ARGUMENTS\""
echo " • /project-orchestrator:debug --spec=\"$BUGFIX_SPEC\""
echo ""
echo "The orchestrator will:"
echo " 1. Add strategic logging across affected files"
echo " 2. Spawn specialist agents per domain"
echo " 3. Coordinate parallel investigation"
echo " 4. Integrate and test all fixes together"
echo ""
exit 0
else
echo ""
echo "✅ Continuing with sequential workflow"
echo ""
echo "Note: You can switch to orchestrator mode anytime by running:"
echo " /debug:coordinate \"<problem-description>\""
echo ""
fi
elif [ "$RECOMMENDATION" = "consider_orchestrator" ]; then
echo "💭 SUGGESTION: Orchestrator may help with this workflow"
echo ""
echo "Complexity signals detected. Consider using orchestrator if:"
echo " • Workflow becomes more complex than expected"
echo " • Multiple iterations needed (log → restart → fix cycle)"
echo " • You find more bugs during investigation"
echo ""
echo "To switch to orchestrator mode, run:"
echo " /debug:coordinate \"<problem-description>\""
echo ""
fi
else
echo "ℹ️ Single bug detected - sequential workflow is optimal"
echo ""
fi
else
echo "ℹ️ Orchestrator detection not available (lib not found)"
echo ""
fi
Continue with normal workflow...
3. Create Regression Test Specification
Create $REGRESSION_TEST_SPEC using this template:
# Regression Test: Bug ${FEATURE_NUM}
**Purpose**: Prove bug exists, validate fix, prevent future regressions
**Test Type**: Regression Test
**Created**: YYYY-MM-DD
---
## Test Objective
Write a test that:
1. ✅ **Fails before fix** (proves bug exists)
2. ✅ **Passes after fix** (proves bug fixed)
3. ✅ **Prevents regression** (catches if bug reintroduced)
---
## Test Specification
### Test Setup
[What needs to be set up before test runs?]
- Initial state
- Test data
- Mock/stub configuration
- Dependencies
### Test Execution
[What actions does the test perform?]
1. Action 1
2. Action 2
3. Action 3
### Test Assertions
[What validations prove bug exists/fixed?]
- ✅ Assertion 1: [expected outcome]
- ✅ Assertion 2: [expected outcome]
- ✅ Assertion 3: [expected outcome]
### Test Teardown
[Any cleanup needed?]
---
## Test Implementation
### Test File Location
[Where should this test live?]
**File**: [path/to/test/file]
**Function/Test Name**: `test_bug_${FEATURE_NUM}_[description]`
### Test Validation Criteria
**Before Fix**:
- ❌ Test MUST fail (proves bug reproduction)
- If test passes before fix, test is invalid
**After Fix**:
- ✅ Test MUST pass (proves bug fixed)
- ✅ All existing tests still pass (no regressions)
---
## Edge Cases to Test
[Related scenarios that should also be tested]
1. Edge case 1
2. Edge case 2
3. Edge case 3
---
## Metadata
**Workflow**: Bugfix (regression-test-first)
**Created By**: SpecLab Plugin v1.0.0
Write regression test specification to $REGRESSION_TEST_SPEC.
Output to user:
📋 Regression Test Specification
✓ Created: ${REGRESSION_TEST_SPEC}
✓ Test must fail before fix, pass after fix
4. Generate Tasks
Create $TASKS_FILE with regression-test-first methodology:
# Tasks: Bug ${FEATURE_NUM} - [Bug Title]
**Workflow**: Bugfix (Regression-Test-First)
**Status**: Active
**Created**: YYYY-MM-DD
---
## Execution Strategy
**Mode**: ${EXECUTION_MODE}
**Smart Integration**:
${INTEGRATION_SUMMARY}
---
## Phase 1: Regression Test Creation
### T001: Write Regression Test
**Description**: Implement test specified in regression-test.md
**File**: [test file path]
**Validation**: Test code follows test specification
**Parallel**: No (foundational)
### T002: Verify Test Fails
**Description**: Run regression test and confirm it fails (proves bug exists)
**Command**: [test command]
**Expected**: Test fails with error matching bug symptoms
**Validation**: Test failure proves bug reproduction
**Parallel**: No (depends on T001)
---
## Phase 2: Bug Fix Implementation
### T003: Implement Fix
**Description**: Apply solution from bugfix.md
**Files**: [list files to modify]
**Changes**: [high-level change description]
**Tech Stack Validation**: ${TECH_VALIDATION_ENABLED}
**Parallel**: No (core fix)
[If multiple independent fixes needed, mark additional tasks with [P]]
### T004: Verify Test Passes
**Description**: Run regression test and confirm it passes (proves bug fixed)
**Command**: [test command]
**Expected**: Test passes
**Validation**: Test success proves bug fixed
**Parallel**: No (depends on T003)
---
## Phase 3: Regression Validation
### T005: Run Full Test Suite
**Description**: Verify no new regressions introduced
**Command**: [full test suite command]
**Expected**: All tests pass (existing + new regression test)
**Validation**: 100% test pass rate
**Parallel**: No (final validation)
[If SpecSwarm installed, add tech stack validation task]
${TECH_STACK_VALIDATION_TASK}
---
## Summary
**Total Tasks**: 5 (minimum)
**Estimated Time**: 1-3 hours (varies by bug complexity)
**Parallel Opportunities**: Limited (regression-test-first is sequential by nature)
**Success Criteria**:
- ✅ Regression test created
- ✅ Test failed before fix (proved bug)
- ✅ Fix implemented
- ✅ Test passed after fix (proved solution)
- ✅ No new regressions
${TECH_COMPLIANCE_CRITERION}
Write tasks to $TASKS_FILE.
Output to user:
📊 Tasks Generated
✓ Created: ${TASKS_FILE}
✓ 5 tasks (regression-test-first methodology)
✓ Phase 1: Create regression test (T001-T002)
✓ Phase 2: Implement fix (T003-T004)
✓ Phase 3: Validate no regressions (T005)
5. Execute Workflow
Now execute the tasks using the appropriate mode:
If SpecTest Installed (Parallel + Hooks):
⚡ Executing Bugfix Workflow with SpecTest Integration
🎣 Pre-Task Hook
✓ Validating prerequisites
✓ Environment ready
Phase 1: Regression Test Creation (T001-T002)
→ T001: Write Regression Test
[execute task]
→ T002: Verify Test Fails
[execute task, confirm failure]
✅ Test failed as expected (bug reproduced)
Phase 2: Bug Fix Implementation (T003-T004)
→ T003: Implement Fix
[execute task]
[if SpecSwarm installed, validate against tech stack]
→ T004: Verify Test Passes
[execute task]
✅ Test passed (bug fixed!)
Phase 3: Regression Validation (T005)
→ T005: Run Full Test Suite
[execute task]
✅ All tests pass (no regressions)
🎣 Post-Workflow Hook
✓ All tasks completed
✓ Bug fixed successfully
✓ Regression test added
✓ No new regressions
📊 Metrics updated
If Only SpecSwarm Installed (Sequential + Tech Validation):
🔧 Executing Bugfix Workflow with SpecSwarm Integration
Phase 1: Regression Test Creation
T001: Write Regression Test
[execute task]
T002: Verify Test Fails
[execute task]
✅ Test failed (bug reproduced)
Phase 2: Bug Fix Implementation
T003: Implement Fix
[execute task]
🔍 Tech Stack Validation
✓ Loading tech stack: .specswarm/tech-stack.md
✓ Validating fix against tech stack
✓ Compliant: All changes follow tech stack
T004: Verify Test Passes
[execute task]
✅ Test passed (bug fixed!)
Phase 3: Regression Validation
T005: Run Full Test Suite
[execute task]
✅ All tests pass (no regressions)
Basic Mode (No Plugins):
🐛 Executing Bugfix Workflow
Phase 1: Regression Test Creation
T001-T002: [execute sequentially]
Phase 2: Bug Fix Implementation
T003-T004: [execute sequentially]
Phase 3: Regression Validation
T005: [execute]
✅ Workflow Complete
Chrome DevTools MCP Integration (Web Projects Only)
If $CHROME_DEVTOOLS_MODE is "enabled", use Chrome DevTools MCP tools for enhanced debugging during test execution:
During T002: Verify Test Fails (Bug Reproduction)
When running regression test to reproduce bug:
if [ "$CHROME_DEVTOOLS_MODE" = "enabled" ]; then
echo ""
echo "🌐 Chrome DevTools MCP Available"
echo " Using MCP tools for enhanced browser debugging..."
echo ""
fi
Available MCP Tools for Bug Investigation:
- list_console_messages - Capture console errors during test execution
- list_network_requests - Monitor API calls and network failures
- get_console_message - Inspect specific error messages
- take_screenshot - Visual evidence of bug state
- evaluate_script - Inspect runtime state (variables, DOM, etc.)
Example Usage During Test Execution:
- After test fails, use
list_console_messagesto capture JavaScript errors - Use
list_network_requeststo identify failed API calls - Use
take_screenshotto document visual bugs - Use
evaluate_scriptto inspect application state when bug occurs
During T004: Verify Test Passes (Fix Validation)
When validating fix works correctly:
if [ "$CHROME_DEVTOOLS_MODE" = "enabled" ]; then
echo ""
echo "🌐 Validating fix with Chrome DevTools MCP..."
echo " ✓ Monitoring console for errors"
echo " ✓ Checking network requests"
echo ""
fi
Validation Checklist:
- ✅ No console errors (use
list_console_messages) - ✅ All network requests succeed (use
list_network_requests) - ✅ Visual state correct (use
take_screenshot) - ✅ Application state valid (use
evaluate_script)
MCP vs Playwright Fallback
If Chrome DevTools MCP is enabled:
- Richer debugging capabilities
- Persistent browser profile (
~/.cache/chrome-devtools-mcp/) - Real-time console monitoring
- Network request inspection
- No Chromium download needed (saves ~200MB)
If using Playwright fallback:
- Standard browser automation
- Downloads Chromium (~200MB) if not installed
- Basic screenshot and interaction capabilities
- Works identically from user perspective
Important: Both modes provide full functionality. Chrome DevTools MCP enhances debugging experience but is NOT required.
Post-Workflow Hook (if SpecTest installed)
if [ "$ENABLE_HOOKS" = "true" ]; then
echo ""
echo "🎣 Post-Bugfix Hook"
# Calculate metrics
WORKFLOW_END_TIME=$(date +%s)
WORKFLOW_DURATION=$((WORKFLOW_END_TIME - WORKFLOW_START_TIME))
WORKFLOW_HOURS=$(echo "scale=1; $WORKFLOW_DURATION / 3600" | bc)
# Validate completion
echo "✓ Bug fixed successfully"
echo "✓ Regression test added"
echo "✓ No new regressions introduced"
# Tech stack compliance
if [ "$SPECSWARM_INSTALLED" = "true" ]; then
echo "✓ Tech stack compliant"
fi
# Update metrics file
METRICS_FILE=".specswarm/workflow-metrics.json"
# [Update JSON with bugfix metrics]
echo "📊 Metrics saved: ${METRICS_FILE}"
echo ""
echo "⏱️ Time to Fix: ${WORKFLOW_HOURS}h"
echo ""
fi
Quality Impact Validation
Purpose: Ensure bug fix doesn't introduce new issues or reduce code quality
YOU MUST NOW validate quality impact using these steps:
-
Check if quality standards exist using the Read tool:
- Try to read
${REPO_ROOT}.specswarm/quality-standards.md - If file doesn't exist: Skip quality validation, go to Final Output
- If file exists: Continue with validation
- Try to read
-
Execute quality validation using the Bash tool:
a. Display header:
🧪 Quality Impact Analysis ==========================b. Run unit tests:
cd ${REPO_ROOT} && npx vitest run --reporter=verbose 2>&1 | tail -50Parse output for test counts (total, passed, failed).
c. Measure code coverage (if tool available):
npx vitest run --coverage 2>&1 | grep -A 10 "Coverage" || echo "Coverage not configured"Parse coverage percentage.
d. Calculate quality score:
- Unit Tests: 25 points if all pass, 0 if any fail
- Coverage: 25 points * (coverage_pct / 80)
- Other components: Use same scoring as implement workflow
-
Compare before/after quality:
a. Load previous quality score from metrics.json:
- Read
${REPO_ROOT}.specswarm/metrics.json - Find most recent quality score before this bugfix
- Store as BEFORE_SCORE
b. Calculate current quality score:
- Use scores from step 2
- Store as AFTER_SCORE
c. Calculate delta:
- QUALITY_DELTA = AFTER_SCORE - BEFORE_SCORE
- Read
-
Display quality impact report:
📊 Quality Impact Report ======================== Before Fix: {BEFORE_SCORE}/100 After Fix: {AFTER_SCORE}/100 Change: {QUALITY_DELTA > 0 ? '+' : ''}{QUALITY_DELTA} points Test Results: - Total Tests: {TOTAL} - Passing: {PASSED} ({PASS_RATE}%) - Failing: {FAILED} Code Coverage: {COVERAGE}% {VERDICT} -
Determine verdict:
a. If QUALITY_DELTA < 0 (quality decreased):
- Display: "⚠️ WARNING: Bug fix reduced code quality by {abs(QUALITY_DELTA)} points"
- Ask user:
This suggests the fix may have introduced new issues. Would you like to: 1. Review the changes and improve quality 2. Continue anyway (NOT RECOMMENDED) 3. Revert fix and try different approach Choose (1/2/3): - If user chooses 1: Halt, suggest improvements
- If user chooses 2: Display strong warning and continue
- If user chooses 3: Offer to revert last commit
b. If QUALITY_DELTA == 0 (no change):
- Display: "✅ Quality maintained - Fix didn't introduce regressions"
- Continue to Final Output
c. If QUALITY_DELTA > 0 (quality improved):
- Display: "🎉 Quality improved! Fix increased quality by {QUALITY_DELTA} points"
- Highlight improvements (more tests passing, higher coverage, etc.)
- Continue to Final Output
-
Save quality metrics:
- Update
${REPO_ROOT}.specswarm/metrics.json - Add quality_delta field to bugfix record
- Include before/after scores
- Update
IMPORTANT: This validation catches regressions introduced by bug fixes. If quality decreases, investigate before proceeding.
Chain Bug Detection (Phase 3 Enhancement)
Purpose: Detect if this bug fix introduced new bugs (prevent Bug 912 → Bug 913 scenarios)
YOU MUST NOW check for chain bugs using the Bash tool:
-
Run chain bug detector:
bash ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/speclabs/lib/chain-bug-detector.sh ${REPO_ROOT} -
Parse detector output:
- Exit code 0: No chain bugs detected (✓ SAFE)
- Exit code 1: Chain bugs detected (⚠️ WARNING)
-
If chain bugs detected:
a. Display warning:
⛓️ CHAIN BUG DETECTED ═══════════════════════ This bug fix may have introduced new issues: - Tests decreased: {BEFORE} → {AFTER} - SSR issues: {COUNT} - TypeScript errors: {COUNT} This suggests the fix created new problems.b. Offer actions:
What would you like to do? 1. Review fix and improve (analyze with /specswarm:analyze-quality) 2. Use orchestrator for complex fix (/speclabs:coordinate) 3. Revert and try different approach (git revert HEAD) 4. Continue anyway (NOT RECOMMENDED) Choose (1/2/3/4):c. Execute user choice:
- Option 1: Run
/specswarm:analyze-qualityfor full analysis - Option 2: Display orchestrator command to use
- Option 3: Offer to revert last commit
- Option 4: Display strong warning and continue
- Option 1: Run
-
If no chain bugs:
- Display: "✓ No chain bugs detected - Fix is clean"
- Continue to Final Output
Impact: Prevents cascading bug fixes (Bug 912 → 913 → 914 chains)
Final Output
✅ Bugfix Workflow Complete - Feature ${FEATURE_NUM}
📋 Artifacts Created:
- ${BUGFIX_SPEC}
- ${REGRESSION_TEST_SPEC}
- ${TASKS_FILE}
📊 Results:
- Bug fixed successfully
- Regression test created and passing
- No new regressions introduced
${TECH_STACK_COMPLIANCE_RESULT}
⏱️ Time to Fix: ${WORKFLOW_DURATION}
${PARALLEL_SPEEDUP_RESULT}
📈 Next Steps:
1. Review artifacts in: ${FEATURE_DIR}
2. Commit changes: git add . && git commit -m "fix: bug ${FEATURE_NUM}"
3. View metrics: /specswarm:workflow-metrics ${FEATURE_NUM}
4. ${SUGGEST_NEXT_COMMAND}
Post-Command Tip (display only for web projects without Chrome DevTools MCP):
if [ "$CHROME_DEVTOOLS_MODE" = "fallback" ]; then
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "💡 TIP: Enhanced Web Debugging Available"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "For web projects, Chrome DevTools MCP provides:"
echo " • Real-time console error monitoring"
echo " • Network request inspection"
echo " • Runtime state debugging"
echo " • Saves ~200MB Chromium download"
echo ""
echo "Install Chrome DevTools MCP:"
echo " claude mcp add ChromeDevTools/chrome-devtools-mcp"
echo ""
echo "Your workflow will automatically use it next time!"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
fi
Error Handling
If branch detection fails:
- Prompt user for bug number
- Offer to create bugfix branch
If feature directory missing:
- Prompt for bug description
- Create feature directory
If regression test fails to fail:
- ❌ Error: "Regression test must fail before fix (proves bug exists)"
- Prompt user to review test or bug specification
If test suite has regressions:
- ❌ Error: "New regressions detected. Fix must not break existing tests."
- List failed tests
- Suggest investigating breaking changes
Operating Principles
- Ultrathink First: Deep multi-layer analysis before jumping to solutions
- Test First: Always write regression test before fixing
- Verify Reproduction: Test must fail to prove bug exists
- Single Responsibility: Each task has one clear goal
- No Regressions: Full test suite must pass
- Tech Compliance: Validate fix against tech stack (if SpecSwarm installed)
- Metrics Tracking: Record time-to-fix, regression coverage
- Smart Integration: Leverage SpecSwarm/SpecTest when available
Best Practice: Ultrathinking
Always use ultrathinking for root cause analysis. Many bugs have multiple layers:
Example - Bug 918 (Password Reset "Already Used" Error):
- Surface symptom: "Reset Link Already Used" error on fresh tokens
- First layer found: Multiple tokens allowed per user (Bug 916)
- Second layer suspected: Frontend caching issue (Bug 917 - red herring)
- ACTUAL root cause (found with ultrathink): Property name mismatch
- Database config:
postgres.cameltransformsused_at→usedAt - Code accessed:
result.used_at(wrong name) → returnedundefined - Logic treated
undefinedas "already used" → fresh tokens rejected
- Database config:
Without ultrathink: Found Bug 916, missed actual cause With ultrathink: Found Bug 918, resolved the issue
Ultrathinking checklist:
- ✅ Check database configuration (transforms, defaults, constraints)
- ✅ Analyze property access patterns (naming mismatches)
- ✅ Examine caching behavior (all layers)
- ✅ Trace data flow end-to-end
- ✅ Look for cascading bugs (one hiding another)
- ✅ Validate assumptions about how libraries work
Success Criteria
✅ Bugfix specification documents bug thoroughly ✅ Regression test created ✅ Test failed before fix (proved bug reproduction) ✅ Fix implemented ✅ Test passed after fix (proved bug fixed) ✅ No new regressions introduced ✅ Tech stack compliant (if SpecSwarm installed) ✅ Metrics tracked (if SpecTest installed)
Workflow Coverage: Addresses ~40% of development work (bug fixes) Integration: Smart detection of SpecSwarm (tech enforcement) and SpecTest (parallel/hooks) Graduation Path: Proven workflow will graduate to SpecSwarm stable