software-design-debugging

SKILL.md

---
name: software-design-debugging
description: Guides systematic debugging with hypotheses, invariants, assertions, contracts, observability, and minimal fixes. Use when investigating bugs, failing tests, surprising behavior, flaky state, crashes, or code that appears to work by coincidence.
---

# Software Design Debugging

## Goal

Find the real cause of a bug and leave the code more diagnosable than before.

## Debugging Workflow

1. Reproduce or characterize the failure.
2. State the expected behavior and the observed behavior.
3. Form one hypothesis at a time.
4. Gather evidence with the narrowest tool: test, log, debugger, trace, or inspection.
5. Identify the broken invariant or missing contract.
6. Apply the smallest fix at the cause, not the symptom.
7. Add a regression check if the behavior can recur.

## Design Checks

- Is the program failing early when an invariant is broken?
- Are assertions checking impossible states during development?
- Are errors represented at the right boundary?
- Can special cases be designed out of existence?
- Does the fix reduce coincidence, hidden state, or temporal coupling?
- Would a future maintainer know why this failed?

## Avoid

- Patching every suspicious site.
- Changing code before stating a hypothesis.
- Swallowing failures that reveal broken assumptions.
- Adding defensive fallback behavior that hides corrupt state.
- Treating a failing test as wrong before understanding its claim.

## Output

```markdown
Debugging report

Failure:
- Expected: <expected behavior>
- Observed: <observed behavior>

Hypothesis tested:
- <claim and evidence>

Root cause:
- <broken assumption or invariant>

Fix:
- <minimal change>

Regression check:
- <test or verification>
```