Debug Mantra
Run a disciplined debug session that forces reproduction, fail-path tracing, hypothesis falsification, and breadcrumb cross-reference before any fix suggestion.
Overview
Debug Mantra is a journey-wide agent skill that enforces a four-step debugging discipline—usable whenever a solo builder needs to investigate failures before committing to a fix.
Install
npx skills add https://github.com/thananon/9arm-skills --skill debug-mantraWhat is this skill?
- Opens every debug session by reciting a four-line mantra block verbatim
- Four ordered steps: reproducibility, fail path, falsify hypothesis, cross-reference breadcrumbs
- Treats flaky bugs as raise-the-rate work until repro is reliable enough to debug
- Explicit stop when no repro exists—ask for data instead of guessing fixes
- Triggers on /debug-mantra, stack traces, and broken/failing user reports
- Four-step mantra sequence with verbatim opening recitation
Adoption & trust: 1.1k installs on skills.sh; 2.7k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You see an error or flaky behavior and the agent jumps to a fix without a reliable repro, traced fail path, or falsified hypothesis.
Who is it for?
Any bug report, stack trace, or failing test where you want the agent to investigate systematically instead of patching symptoms.
Skip if: Pure feature greenfield work with no failure signal, or cases where you already have a verified fix and only need a one-line apply without investigation.
When should I use this skill?
Trigger on /debug-mantra and proactively when debugging starts—broken/failing reports, diagnose/investigate requests, or pasted stack traces and error logs.
What do I get? / Deliverables
The session starts with the mantra, produces a repro or explicit gap, traces failure with evidence, and only then proposes fixes grounded in correlated runs.
- Verbatim mantra recitation in the first response
- Runnable repro artifact or explicit no-repro stop
- Hypothesis list with disproof attempts and correlated run notes
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
A new API endpoint throws 500s—capture a curl repro and trace the fail path before editing handlers.
CI flake at 30%—loop the test until repro is reliable, then instrument the suspected branch.
User pastes production logs; cross-reference breadcrumbs across deploys instead of guessing config drift.
Support ticket says checkout broke—require repro steps from the reporter before changing payment code.
Spike demo crashes on demo day—mantra-first session to separate prototype shortcuts from real defects.
How it compares
Structured debugging ritual—not a log aggregator, test runner, or automated root-cause MCP server.
Common Questions / FAQ
Who is debug-mantra for?
Solo and indie builders using coding agents who want a fixed investigative order before any bug fix is suggested.
When should I use debug-mantra?
During Build when integration tests fail; during Ship when pre-release regressions appear; during Operate when production errors or flaky jobs need diagnosis; and anytime you invoke /debug-mantra or paste a stack trace.
Is debug-mantra safe to install?
The skill is procedural text; review the Security Audits panel on this page and limit agent permissions if instrumentation requires shell or network on production systems.
SKILL.md
READMESKILL.md - Debug Mantra
# Debug Mantra Four-step discipline for any debug session. Recite verbatim, then apply in order. ## Recite this — verbatim, as the first thing in your first response > **Mantra:** > 1. **First is reproducibility.** Can the issue be reproduced reliably? > 2. **Know the fail path.** Debugger first; then source trace + knob enumeration; then in-code instrumentation. > 3. **Question your hypothesis.** What would disprove it? > 4. **Every run is a breadcrumb.** Cross-reference all of them. Then begin work. --- ## 1. Reproduce reliably Build a runnable repro before anything else. - **Reliable repro** → capture the exact steps, inputs, and environment as a runnable artifact: failing test, curl script, CLI invocation, replay harness. - **Flaky repro** → the bug is not yet debuggable. Raise the rate first: loop the trigger, parallelise, add stress, narrow timing windows, inject sleeps. 50% flake is debuggable; 1% is not. - **No repro at all** → stop. Say so explicitly. Ask the user for env access, captured artifacts (HAR, log dump, core), or permission to instrument. Do **not** proceed to hypothesise. Target: a fast (1–5 s), deterministic pass/fail signal. Pin time, seed the RNG, freeze network, isolate filesystem. ## 2. Know the fail path Once reproducible, find *where* the code breaks and *what stops it from breaking*. The differential narrows the search. Try in this order — escalate only when the prior tactic fails. 1. **Attach a debugger.** If the env supports it, attach and step to the failure site. One breakpoint beats ten logs. Do this **before** turning any knobs. 2. **Source trace + knob enumeration.** If no debugger (or it can't reach the bug), trace the code path end-to-end and list every knob that can influence the outcome: - config flags, env vars, feature toggles - branch conditions, input shape - timing, concurrency, build options Each knob is a candidate axis to flip in the differential. Flip one at a time. 3. **In-code instrumentation.** If outside knobs can't move the failure, go inside: `printf` / log statements at the suspected fail site, dump the relevant internal state. Tag every probe with a unique prefix (e.g. `[DBG-a4f2]`) so cleanup is a single grep. Let the trace show where reality diverges from your model. ## 3. Falsify the hypothesis When a candidate root cause surfaces, scrutinise it **before** testing it. - Does it actually explain the symptom end-to-end? Walk it through. - What is the simplest **proof**? What is the cleanest **disproof**? - Run the **disproof first**. If the hypothesis survives, it's real. If it dies, you saved yourself from chasing a phantom. - Generate 3–5 ranked hypotheses, not one. Single-hypothesis thinking anchors on the first plausible idea. ## 4. Every run is a breadcrumb Maintain a running **ledger** of every experiment in this session. Each entry: what changed, what happened, what it ruled in or out. - When a new hypothesis surfaces, walk the ledger. Does it hold for **every** prior observation, not just the most recent? - If any past run contradicts it, the hypothesis is wrong or incomplete — refine or discard. - When in doubt, design the **single experiment** whose outcome makes it certain. Run that next, instead of churning on adjacent runs. - Update the ledger after every run. It is your memory across the session. --- ## Operating rules - Recite the mantra block **once** per debug session, in your first response. Do not re-recite mid-ses