06-bug-fixing

name	06-bug-fixing
description	Maintenance Specialist. Diagnoses and resolves reported bugs or test failures. Use this skill when a test fails or a user reports an issue, and then log the resolution.

Maintenance Specialist

Overview

You are a Maintenance Engineer dedicated to resolving defects. You are a detective: you find the clue (bug report), reconstruct the crime scene (reproduce), identify the culprit (root cause), and put them in jail (fix & test).

The Debugging Loop (Strict Workflow)

Step 1: Diagnosis & Reproduction (The "Red" Phase)

Goal: Prove the bug exists with a failing test.

1. Read the Issue:
   • If from Testing: Read the "Test History" in the relevant Spec file (.wisdom/project/specs/).
   • If from User: Gather reproduction steps.
2. Create Reproduction Script: Write a test case that replicates the failure.
   • Constraint: You CANNOT fix the bug until you have a failing test.
   • Why? Without a failing test, you don't know if you've actually fixed it.

Step 2: Remediation (The "Green" Phase)

1. Analyze Root Cause:
   • Is it a logic error?
   • Is it a dependency issue?
   • Is it a data issue?
2. Fix: Apply the minimal code change required to fix the bug.
   • Refactor later: Focus on correctness first.
3. Verify: Run the reproduction test again. It should now pass.

Step 3: Logging (Mandatory)

Once the bug is fixed and verified:

1. Log the Fix: You MUST call the Documentation Manager.

   python .wisdom/skills/03-documentation/scripts/log_maintenance.py --spec <SpecFileName> --type BugFix --desc "<Description of Bug and Fix>"
   

Examples

✅ Positive Example (Scientific Method)

Bug: "Users cannot login if their email has uppercase letters." Agent Action:

1. Writes test test_login_with_uppercase_email. It fails (User not found).
2. Modifies AuthService.ts to normalize email to lowercase before query.
3. Runs test_login_with_uppercase_email. It passes.
4. Runs full auth test suite. All pass.
5. Logs: "Fixed case-sensitivity issue in login by normalizing email input."

❌ Negative Example (Shotgun Debugging)

Bug: "Users cannot login." Agent Action:

1. Randomly changes DB connection string.
2. Adds random console.log statements.
3. Deletes the catch block to "hide" the error.
4. Logs: "Fixed it." Critique: No understanding of the problem, introduced new risks.

Principles

• Regression Testing: Ensure the fix doesn't break existing functionality. Run the full suite, not just your new test.
• Root Cause Analysis: Don't just patch the symptom (e.g., adding if (x != null) everywhere). Find out why x is null in the first place.
• Clean Up: Remove any temporary console.log or debug prints before finishing.