systematic-debugging

Files (11)

• CREATION-LOG.md
• SKILL.md
• condition-based-waiting-example.ts
• condition-based-waiting.md
• defense-in-depth.md
• find-polluter.sh
• root-cause-tracing.md
• test-academic.md
• test-pressure-1.md
• test-pressure-2.md
• test-pressure-3.md

SKILL.md (first lines)

# Systematic Debugging

Root cause, evidence, reproduction, and semantic verification prevent plausible
patches from becoming recurring failures. Use this workflow when root cause or
behavior is genuinely unclear, a failure repeats, components cross a boundary, or
risk makes a guess unsafe. A known, determined small repair may proceed directly
with suitable verification.

## Investigation lenses

The following are composable investigation lenses, not mandatory consecutive
phases: observe/reproduce the meaningful symptom; inspect recent state and
relevant boundaries; compare a working analogue; trace input or control flow;
form a single hypothesis; run the smallest discriminating experiment. Select the
lenses that reduce the uncertainty at hand and preserve the evidence.

Use a failing automated test when there is a meaningful seam. Otherwise use the
strongest suitable reproduction, counterfactual, or readback. After a root fix,
run semantic verification of the affected behavior and relevant regressions.

## Escalation and containment

When evidence shows shared state, hidden coupling, or each attempted fix moves
the symptom, reassess the architecture before stacking more local changes. This
is evidence-driven, not a fixed failure count.

A clearly labeled containment or mitigation may reduce harm while root cause is
still under investigation. It must state its limitation and must not be presented as a root fix.

## Supporting references

- `root-cause-tracing.md` for tracing a deep symptom to its original trigger.
- `defense-in-depth.md` for safeguards across distinct trust boundaries and
  failure modes.
- `condition-based-waiting.md` for replacing arbitrary timing with observed
  conditions.

From BB-84C/superpowers-lite, MIT.

More from BB-84C/superpowers-lite