Better Bug Fix

Better Bug Fix

Follow a test-first debugging workflow that proves the bug and validates the fix.

Workflow

1. Triage and scope the bug.

   • Restate the symptom and expected behavior in one sentence.
   • Identify the affected area (files, module, API, UI).

2. Write a minimal failing test first.

   • Add the smallest test that reproduces the bug.
   • Prefer existing test frameworks and patterns in the repo.
   • If no tests exist, create a minimal repro harness as close as possible to existing structure.

3. Run tests to confirm failure.

   • Execute the narrowest test command that includes the new test.
   • Record the failing output or error signature.

4. Delegate fixes to subagents.

   • Spawn 2-3 subagents with clear ownership of investigation/​fix ideas.
   • Ask each to propose a fix and the rationale, referencing the failing test.
   • Keep their scopes non-overlapping (e.g., data flow, edge cases, API contract).

5. Implement the best fix.

   • Apply the most plausible fix based on test and codebase conventions.
   • Keep the change minimal and focused on the bug.

6. Prove the fix.

   • Re-run the failing test(s) and any relevant nearby tests.
   • Ensure the new test passes and no regressions are introduced.

7. Report clearly.

   • Explain the root cause, the test added, and why the fix works.
   • Call out any remaining risks or follow-ups.

Guardrails

• Do not attempt a fix before a reproducing test exists.
• If a test cannot be written, explicitly explain why and propose the closest alternative (repro script or manual steps).
• Avoid refactors unless necessary to make the test feasible.
• Keep changes small; prefer surgical fixes.

Subagent Prompt Template

Use this template when spawning subagents:

"""

You are a subagent investigating a bug. The reproducing test is failing. Please:

1. Identify the likely root cause in the code.
2. Propose a minimal fix.
3. Note any tradeoffs or additional tests to add.

Stay within your assigned scope.

"""