Bug Fix Workflow

This skill defines the bug fixing workflow. It guides systematic debugging from initial symptom to verified fix.

Cycle Overview

INVESTIGATE → REPRODUCE → TEST → FIX → COMMIT

Human approval required before each phase transition.

Phase Details

INVESTIGATE: Find Root Cause

Agent: review-agent

Actions:

1. •Read bug report or symptom description
2. •Create .bugfix_context.md with initial symptom
3. •Trace code paths related to the symptom
4. •Read error logs, stack traces if available
5. •Form root cause hypothesis
6. •Document findings in .bugfix_context.md

Output: Root cause hypothesis with supporting evidence

Exit: Human approves hypothesis → proceed to REPRODUCE

REPRODUCE: Confirm the Bug

Agent: review-agent

Actions:

1. •Design minimal reproduction steps
2. •Execute reproduction to confirm bug exists
3. •Document exact steps in .bugfix_context.md
4. •Note any environment or data dependencies

Output: Reproducible test case (manual steps or script)

Exit: Bug reliably reproduced → proceed to TEST

TEST: Write Regression Test

Agent: tdd-test-writer

Actions:

1. •Read .bugfix_context.md for reproduction steps and root cause
2. •Write failing test that captures the bug
3. •Run test to confirm failure
4. •Update .bugfix_context.md with test location

Rules:

• •Test should fail for the exact reason identified in INVESTIGATE
• •Test name should describe the bug: should_handle_special_chars_in_password
• •Keep test minimal — only what's needed to catch this bug

Exit: Failing test approved → proceed to FIX

FIX: Implement Minimal Fix

Agent: implementation-agent

Actions:

1. •Read .bugfix_context.md for context
2. •Implement minimal fix to pass the regression test
3. •Run full test suite to ensure no regressions
4. •Update .bugfix_context.md with fix description

Rules:

• •Fix only what's broken — no scope creep
• •Don't refactor unrelated code
• •If fix reveals deeper issues, document them for separate work

Exit: All tests pass → proceed to COMMIT

COMMIT: Commit the Fix

Actions:

1. •Stage regression test and fix
2. •Generate commit message with fix: prefix
3. •Human approves commit
4. •Commit changes

Commit Message Format:

fix: <short description>

<optional body explaining the root cause and fix>

Closes #<issue-number> (if applicable)

Exit: Committed → bug fix cycle complete

Context File

.bugfix_context.md tracks state across phases:

# Bug Fix Context

**Bug**: Login fails for users with special characters in password
**Reported**: 2026-01-29
**Current Phase**: FIX

## Symptom

Users with passwords containing `&` or `=` cannot log in.
Error: "Invalid credentials" even with correct password.

## Investigation Findings

- Auth endpoint at `src/auth/login.ts:45`
- Password passed through URL query param (line 52)
- Special chars not URL-encoded before comparison
- Root cause: `&` splits the query string prematurely

## Reproduction Steps

1. Create user with password `test&pass=123`
2. Attempt login via POST /auth/login
3. Observe 401 response

## Regression Test

Location: `test/auth/login.test.ts`
Test: `should_authenticate_user_with_special_chars_in_password`

## Fix Description

URL-encode password before query string construction in `src/auth/login.ts:52`

When to Use This Workflow

Use bug-fix-cycle when:

• •Fixing reported bugs or errors
• •Debugging unexpected behavior
• •Addressing failing tests in production
• •Investigating user-reported issues

Do NOT use for:

• •New features → use feature-cycle
• •Refactoring working code → use refactor-agent directly
• •Pure investigation with no fix needed → exit early after INVESTIGATE

Anti-Patterns

• •Skipping INVESTIGATE and guessing the fix
• •Fixing without a regression test
• •Expanding scope beyond the reported bug
• •Committing without running full test suite