Bug Planning Skill

Plan surgical bug fixes with root cause analysis and regression prevention.

When to Apply

Activate when:

• Story title contains: Fix, Resolve, Correct, Handle, Repair, Bug, Error
• Story describes unexpected or incorrect behavior
• Story references error conditions or exceptions
• User story follows "I expect [behavior] but [actual]" pattern

Focus Areas

When planning bug fix stories, emphasize:

1. Root Cause: Why is this happening?
2. Minimal Fix: Smallest change that fixes it
3. Regression: Ensure no new bugs introduced
4. Verification: Prove the fix works

Context Gathering

Before planning, analyze:

• Steps to reproduce the bug
• Expected vs actual behavior
• Related code paths
• Existing test coverage

Plan Output Format

Write to {story_path}/plan.md:

# Implementation Plan: {Story Title}

## Metadata
- **Story**: {story_id}
- **Feature**: {feature_id}
- **Type**: bug (inferred)
- **Created**: {timestamp}
- **Severity**: {Low/Medium/High/Critical}

## Bug Description
{Symptoms and user impact}

## Steps to Reproduce
1. {exact step}
2. {exact step}
3. {observe bug}

## Expected vs Actual

| Expected | Actual |
|----------|--------|
| {what should happen} | {what happens} |

## Root Cause Analysis
{Deep analysis of why this is happening - trace the code path}

## Proposed Fix
{Minimal change description - be specific about what will change}

## Code Impact Matrix

| File | Action | Risk | Notes |
|------|--------|------|-------|
| path/to/file | Modify | Low | {minimal change} |

**Scope Constraint**: This matrix should be MINIMAL. If you're touching more than 3-4 files, reconsider the approach.

## Implementation Steps

### Step 1: {Reproduce Bug}
- Confirm bug exists with reproduction steps
- Document current behavior

### Step 2: {Apply Fix}
- **File**: `path/to/file`
- **Change**: {specific change}
- **Why**: {how this addresses root cause}

### Step 3: {Add Regression Test}
- Create test that would have caught this bug
- Ensure test fails before fix, passes after

### Step 4: {Verify Fix}
- Run reproduction steps
- Confirm expected behavior

## Test Strategy

### Regression Test (Required)
- [ ] Test that reproduces the bug (must fail before fix)

### Related Tests
- [ ] {existing tests to run}

## Verification Commands
```bash
# Before fix: reproduce bug
{command to show bug}

# After fix: verify resolution
{command to show fix works}

# Run test suite
{test command}

Rollback Plan

{How to undo - usually just revert the commit}

Notes

{Any context for future developers}

## Constraints

**CRITICAL - Bug fixes have strict boundaries:**

- NO new features
- NO refactoring
- NO "while we're here" changes
- NO scope creep
- ONLY fix the reported bug

If you find other issues during investigation, create separate stories for them.

## Applying This Skill

When creating a bug plan:

1. Document exact reproduction steps first
2. Investigate and understand root cause deeply
3. Propose the smallest possible fix
4. Plan regression test that would catch this bug
5. Define clear before/after verification
6. Keep the scope extremely tight
7. Create separate stories for any other issues found