# Assistant Debugging

> Diagnose an unknown failure by reproducing and isolating before fixing. Use for debugging, root causes, flaky tests, or unexplained breakage.

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

---


# Evidence-First Debugging

## Goal

Find and fix the real cause of a failure with the smallest durable change and
evidence that explains the symptom, cause, fix, and verification.

## Success Criteria

- The symptom and expected behavior are explicit.
- Reproduction evidence exists, or an exact blocker explains why it cannot.
- Competing hypotheses are tested and disconfirming evidence is retained.
- Root cause is supported by code, config, or runtime evidence.
- Verification covers the original failure path and a relevant regression check.

## Constraints

- Use local, company-safe diagnostics by default; redact secrets and private data.
- Ask before destructive, production-affecting, network, migration, or sensitive-data diagnostics.
- Do not patch from a guess or claim root cause when evidence supports only mitigation.
- Ask for missing context only when it materially blocks safe reproduction or isolation.

## Progressive Contract Loading

Canonical tier files are `contracts/input.yaml`, `contracts/output.yaml`,
`contracts/phase-gates.yaml`, and `contracts/handoffs.yaml`.

Read `contracts/index.yaml` first. Canonical contracts remain authoritative, but
load only the boundary currently being enforced:

- `entry` for symptom, scope, reproduction target, safety, and edit permission;
- `current_phase` for SCOPE, REPRODUCE, HYPOTHESIZE, ISOLATE, FIX, or VERIFY;
- `selected_handoff` only when investigation or fix delegation is selected; and
- `completion` only for the artifact being returned.

If a selector is missing or invalid, load the full named canonical contract.
Do not load every contract at entry.

## Ownership

assistant-debugging owns diagnosis until the failure mechanism is reproducible
or bounded strongly enough for a fix. Generic workflow may coordinate planning,
delegation, and review, but specialist gates are authoritative.

## Method

1. **SCOPE** — capture symptom, expected behavior, affected path, recent changes,
   constraints, and severity.
2. **REPRODUCE** — run the smallest safe failing test/command or record the exact
   blocker with available log/code/config evidence.
3. **HYPOTHESIZE** — keep at least three plausible causes unless evidence
   justifies fewer. Rank by likelihood, diagnostic cost, and blast radius.
4. **ISOLATE** — run the cheapest high-signal check first. Track supporting and
   disconfirming evidence until one cause predicts the symptom and fix.
5. **FIX** — add a regression test when feasible, then make the smallest change
   that addresses the cause. Label uncertain emergency changes as mitigations.
6. **VERIFY** — rerun the reproduction, focused test, relevant regressions, and
   normal project checks. Skipped checks remain residual risk.

Use `assistant-debugging` before `assistant-tdd` when a meaningful RED test
cannot yet be written. Once the mechanism is understood, hand the regression
test and evidence into the TDD cycle. Use `assistant-review` after non-trivial or
risky fixes.

## Output

Return status, symptom, reproduction or blocker, ranked hypotheses, root cause
and confidence, fix summary, verification results, and residual risks.

## Stop Rules

- Stop before speculative edits when the failure is neither reproduced nor bounded.
- Stop and ask before unsafe diagnostics.
- If every hypothesis is refuted, gather new evidence instead of cycling guesses.
- Use `mitigated` or `inconclusive` when proof is insufficient for root cause.