# Systematic Debugging

> Investigate a failure with an unclear cause, repeated unsuccessful fixes, or a cross-component boundary. Use existing reproduction evidence for a localized bug; not a mandatory multi-stage ritual for every edit.

- Skill: `compozy/systematic-debugging` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add compozy/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/compozy/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: compozy (https://skillmd.com/u/compozy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/compozy/systematic-debugging

---


# Diagnose Before Repair

For a clear localized failure, use the short path: read the diagnostic and relevant change, reproduce or reuse its evidence, locate the owning cause, repair it, and verify the symptom in the existing suite/probe.

Expand investigation when the evidence does not explain the failure:

- Trace the bad value or lifetime to its source; compare relevant working code and contracts. `root-cause-tracing.md` describes backward tracing when the call chain is unclear.
- Instrument only the unresolved boundary, using safe summaries rather than dumping credentials or whole environments. Gather enough evidence to distinguish hypotheses.
- Test a concrete causal hypothesis with the smallest useful experiment. After a failed attempt, update the hypothesis from the result; an arbitrary attempt count does not itself require an architecture meeting.
- Use `condition-based-waiting.md` for readiness/timing problems. `defense-in-depth.md` applies when independently trusted boundaries need validation, not as a reason to duplicate checks throughout domain code.

Add a focused regression where no existing check owns the invariant. A failing production regression is fixed in production; an invalid test needs contract evidence before its expectation changes. Preserve required compatibility adapters and avoid unrelated cleanup.

Run the affected check and required project gates. Reuse evidence for unchanged inputs; widen only for relevant changes, failures, or unresolved risk. If reproduction is unavailable, state the evidence and uncertainty and continue useful investigation. Ask only for a decision or information that actually blocks progress.

For external defects, isolate the necessary handling and its removal condition with `no-workarounds`. Do not claim a causal fix or completion beyond the available evidence.