systematic-debugging

name	systematic-debugging
description	Use for bugs, failing tests, and unexpected behavior; enforce a 4-phase root-cause-first debugging process before implementing fixes.

Systematic Debugging

Do not jump to fixes. Find root cause first.

4-phase process

1) Root-cause investigation

• Reproduce issue with explicit steps.
• Read errors/stack traces fully.
• Check recent changes likely to affect behavior.
• Gather targeted evidence at component boundaries.

2) Pattern identification

• Find similar working code/path.
• Compare working vs failing flow.
• List concrete differences.

3) Hypothesis test

• Form one hypothesis at a time.
• Apply the smallest possible change to test it.
• Validate hypothesis before moving to additional changes.

4) Minimal fix + validation

• Implement only the root-cause fix.
• Re-run reproduction and verification commands.
• Confirm no collateral regressions in affected scope.

Guardrails

• If 2+ blind fixes already failed, restart at Phase 1.
• If 3+ attempts fail, escalate: question architecture/pattern choice.
• Never report success without applying verification-before-completion.

Supporting techniques (use when applicable)

• root-cause-tracing.md for deep stack tracing.
• condition-based-waiting.md for async/timing issues.
• defense-in-depth.md for post-fix boundary hardening.
• find-polluter.sh when isolated test passes but suite fails.

In this workflow

• Trigger automatically for /pwf-work and /pwf-work-plan when the task is bug/debug/failure oriented.