---
name: debug
description: Debug a code bug with a structured debug log that records hypotheses, changes, and results.
---

<!-- Vendored from marin-community/marin-style v0.3.0 — do not edit; re-run `marin-style sync`. -->

# Skill: Debug

Systematic debugging for code-level bugs. Keep a structured debug log so each
hypothesis, the change that tests it, and its result are recorded — this keeps a
long investigation from looping and makes the reasoning reviewable.

For infrastructure or operational faults, first read any operations runbook the
repo provides and follow its matching section; the guardrails there (what you may
and may not touch on shared infrastructure) take precedence.

## Code bugs

Maintain a debug log at `docs/debug-log-<task-name>.md`:

```
# Debugging log for <task>

<goal>

## Initial status
<initial status, as reported or observed>

## <Hypothesis N>
The suspected source of the bug, or a change needed to isolate it.

## Changes to make
Which files you are altering and how.

## Results
Test results and any new hypotheses. Repeat the Hypothesis/Results cycle as needed.

## Future work
- [ ] Cleanups observed along the way
```

Work one hypothesis at a time: state it, make the smallest change that confirms
or refutes it, record the result, then move on. When the fix lands, capture a
regression test (see the `write-tests` skill) so the bug cannot return silently.