shadow-debug
Skill1 starsChanged yesterdayMITView on GitHub
Systematic Root-Cause Debugging Engineering. Use when diagnosing unexpected bugs, 500 errors, flaky tests, memory leaks, race symptoms, environment drift, or misleading stack traces. Do NOT use for post-prod SLA/Harwat process (shadow-maintain), telemetry setup (shadow-observe), load benchmarking (shadow-perf), or broad code restructuring (shadow-refactor).
In this repository51 other files it gives its agents.
- antislop-codeSkill
- antislop-copywritingSkill
- antislop-humanSkill
- antislop-layoutmobileSkill
- antislopSkill
- antislop-uiSkill
- context7Skill
- handoffSkill
- shadow-accessibilitySkill
- shadow-apiSkill
- shadow-architectSkill
- shadow-authSkill
- shadow-bootstrapSkill
- shadow-browserSkill
- shadow-cacheSkill
- shadow-compatSkill
- shadow-concurrencySkill
- shadow-dataSkill
- shadow-dbSkill
- shadow-designSkill
- shadow-discoverySkill
- shadow-docSkill
- shadow-domainSkill
- shadow-eaSkill
- shadow-evalSkill
- shadow-finopsSkill
- shadow-gitSkill
- shadow-grcSkill
- shadow-handoverSkill
- shadow-integrateSkill
- shadow-maintainSkill
- shadow-mobileSkill
- shadow-modernizeSkill
- shadow-monarchSkill
- shadow-observeSkill
- shadow-opsSkill
- shadow-perfSkill
- shadow-planSkill
- shadow-pmoSkill
- shadow-presalesSkill
- shadow-privacySkill
- shadow-qualitySkill
- shadow-realtimeSkill
- shadow-refactorSkill
- shadow-releaseSkill
- shadow-resilienceSkill
- shadow-searchSkill
- shadow-secSkill
- shadow-supplychainSkill
- shadow-testSkill
- shadow-uatSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Default Access: Read-only inspection (read_repository, run_local_tests).
- Distinctive: line 13
Missing Evidence Rule: If logs, stack traces, or environment reproduction are unavailable, mark missing evidence explicitly and propose …
- Distinctive: line 14
Escalation: If diagnosis requires live production data access without authorization, stop at safe local reproduction plan + escalation …
- Very specific: line 17
Read methodologies/SCIENTIFIC-DEBUGGING-AND-FAULT-TREES.md and playbooks/DEBUG-REPORT-AND-REPRO-TEMPLATE.md when executing complex …
- Very specific: line 21
Minimal Isolated Reproduction: Create a minimal deterministic test or fixture reproducing the failure (FAIL exit code != 0).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/shadow-debug — Systematic Debugging & Root-Cause Engineering
- Owner: Causal diagnosis of software failures with minimal reproduction and red-before/green-after proof.
- Boundaries: Post-prod SLA/Harwat triage (
shadow-maintain), OTel/alert platform setup (shadow-observe), load tests (shadow-perf), code-structure refactor (shadow-refactor).
1. Preconditions, Permissions & Failure Handling
- Default Access: Read-only inspection (
read_repository,run_local_tests). Never mutate production DBs/containers or expose secrets/PII in logs ordebug-report.md. - Missing Evidence Rule: If logs, stack traces, or environment reproduction are unavailable, mark missing evidence explicitly and propose safe instrumentation rather than guessing root cause from a single coincidental error line.
- Escalation: If diagnosis requires live production data access without authorization, stop at safe local reproduction plan + escalation request.
2. 8-Step Scientific Debugging Playbook
Read methodologies/SCIENTIFIC-DEBUGGING-AND-FAULT-TREES.md and playbooks/DEBUG-REPORT-AND-REPRO-TEMPLATE.md when executing complex diagnosis:
- Capture Symptom & Scope: Expected vs actual behavior, severity, first occurrence, affected env/version.
- Build Redacted Timeline: Correlate logs, W3C
traceparent/requestId, commits (git bisect), and env drift; redact tokens/PII. - Rank Testable Hypotheses (>= 2): Pair each hypothesis with explicit disconfirming observations and safe probes (never stop at the first plausible log line).
- Minimal Isolated Reproduction: Create a minimal deterministic test or fixture reproducing the failure (
FAILexit code !=0). - Pinpoint Minimal Root Cause: Separate symptom, contributing factor, and causal mechanism using targeted instrumentation or bisect.
- Failing-Before Regression Test: Record red-before run proving the test catches the exact bug.
- Minimal Behavior-Preserving Fix: Apply smallest consistent change (
§4.1); execute targeted + adjacent regression suites (PASSexit code ==0). - Report & Recurrence Prevention: Emit
debug-report.mdusing the shared evidence envelope (PASS | FAIL | NOT_RUN | BLOCKED).
3. Examples (Happy, Ambiguous, Failure) & Deterministic Gate
- Happy Path: API returns intermittent
500-> trace shows worker ack race -> 2 hypotheses tested -> red test added -> atomic fix -> green suite. - Ambiguous Case: Bug only occurs in staging, not local -> compare env vars, lockfiles, timezone, pool limits before touching code.
- Failure / Must-Reject: Report claims root cause solely from 1 coincidental log line with no disconfirming probe or failing-before test -> BLOCKED by
debug_hypothesis_gate.py.
python "shadow-debug/scripts/debug_hypothesis_gate.py" --self-test
python "shadow-debug/scripts/debug_hypothesis_gate.py" --validate-report path/to/debug-report.json4. Execution Approval & Intent Boundary (L0–L4)
- Log/config/code diagnosis is
L0_READ_ONLY; minimal local reproduction tests are boundedL1_SAFE_VERIFICATIONinside verified local/sandbox targets. Debugging NEVER authorizesL3stress/load testing orL4staging/production/unknown mutations without the 7-part approval contract (shadow-monarch/scripts/execution_approval_gate.py).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

