debug

What it does and when to use it

Debug a failing command, bug, flake, runtime error, wrong output, or performance regression with evidence: reproduce, minimize, hypothesize, instrument, fix, and regression-test. Use when the user asks to debug, diagnose, fix a failure, or use debug-loop.

How it works

1. Unix/Pi Contract
2. Use
3. Workflow
4. Guardrails
5. Output

---
name: debug
description: Debug a failing command, bug, flake, runtime error, wrong output, or performance regression with evidence: reproduce, minimize, hypothesize, instrument, fix, and regression-test. Use when the user asks to debug, diagnose, fix a failure, or use debug-loop.
---

# debug

Find root cause before changing code.

## Unix/Pi Contract

- Do one job: turn a symptom into root cause, fix, and regression proof.
- Consume an exact repro, logs, runtime state, and code path; emit cause, patch, and proof.
- Keep output bounded: inspect high-signal tails, focused files, and direct repros.
- Use shell and repo-native tools first; use heavier tooling only when it improves observation.
- After two identical failures, change hypothesis or instrumentation.

## Use

Use for failing tests, CI failures, crashes, hangs, flakes, broken UI flows, bad output, slow paths, and environment drift.

## Workflow

1. Reproduce the symptom with the exact command, URL, or workflow.
2. Minimize to the smallest failing surface.
3. State one current hypothesis and the evidence that would disprove it.
4. Inspect the code path and runtime state that can affect the symptom.
5. Add temporary instrumentation only when observation is otherwise impossible; remove it before finishing.
6. Fix the root cause, not just the observed error string.
7. Add or identify a regression proof and rerun the original repro.

## Guardrails

- Do not guess from logs alone when a repro is available.
- Do not widen the fix until the local cause is understood.
- Treat hangs and concurrency failures as first-class symptoms; use timeouts, logs, and serialized repros.
- Separate pre-existing unrelated failures from failures caused by the edit.

## Output

Return:

1. Symptom and repro.
2. Root cause.
3. Fix.
4. Regression proof.
5. Commands and results.
6. Remaining risks or external blockers.

Versions

Database snapshot: 13.11.2026 · package version 6d6f23d0c7e6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

• 90diagnose
  Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
• 90dev-debug
  Use when something is broken: a bug, failing test, regression, crash or error in logs.
• 90diagnose
  Use this skill when the user reports a bug, says something is broken, throwing errors, or failing — even if they don't say "diagnose" or "debug". Also use for performance regressions, when the user says something is slow, degraded, or slower than before. Follows a feedback-loop…
• 100m-debug
  Root-cause a bug or failing test: reproduce, competing hypotheses, regression test. Use for debug一下/为什么报错/这个测试挂了.
• 100code-debug
  Find and fix a bug whose cause is not known yet, or a performance regression. Build a command that goes red on the bug, narrow it to the first place the system went wrong, fix it there, and lock it with a regression test. Use when something is broken, throwing, failing, flaky or…
• 100diagnose
  Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce -> minimise -> hypothesise -> instrument -> fix -> regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.