---
name: systematic-debugging
description:
  "Systematic debugging for bugs, failing tests, regressions (TSL/C++/Python).
  Triggers: debug, failing test, regression, crash, 复现, 定位, 排查, 调试."
---

# Systematic Debugging（系统化调试）

## When to Use

- Bugs, crashes, failing/flaky tests, regressions
- “It doesn’t work” reports with unclear reproduction

## Inputs（required）

- Expected vs actual behavior
- Repro command/steps (or best-known approximation)
- Logs/traces/screenshots/error output
- Environment details (OS, versions, configs)

## Procedure（default）

1. **Reproduce**
   - Make the failure deterministic if possible
   - Minimize repro steps (smallest input/command)

2. **Localize**
   - Identify failing component and boundary conditions
   - Add temporary logging/assertions if needed (then remove)

3. **Hypothesize & Test**
   - Form a small number of hypotheses
   - Design quick experiments to falsify each hypothesis

4. **Fix & Verify**
   - Fix the root cause (not just symptoms)
   - Add/update tests; rerun the minimal relevant suite

## Output Contract（stable）

- Repro: exact steps/command
- Diagnosis: root cause + evidence
- Fix: what changed + why it works
- Verification: commands + outputs/exit codes
- Follow-ups: hardening or cleanup tasks

## Guardrails

- Avoid changing multiple variables at once
- Prefer instrumentation and evidence over guessing
- Keep fixes minimal and scoped