{
  "markdown": "<p align=\"center\"><img src=\"logo.png\" width=\"120\" alt=\"logo\" /></p>\n\n# debug-code\n\nA portable Agent Skill for diagnosing hard production and legacy-code bugs when production access is partial or unavailable. It teaches a coding assistant to find the **earliest violated invariant**, not merely the line where the failure surfaces, and to produce the smallest safe fix with proof proportionate to the available access.\n\n**[→ Live site](https://cskwork.github.io/debug-code-skill/)** · **[→ SKILL.md](SKILL.md)**\n\n## Why this skill\n\nProduction bugs are hard because access is partial: you have the code, but logs are on request, the DB needs an operator, and tracing may be missing. The skill does not block on ideal access. It works in **code-only mode** and tightens proof as evidence becomes available.\n\nCore behaviors the skill enforces:\n\n- **Incident gate** — if the symptom suggests active harm (data corruption, duplicate financial effects, unbounded resource exhaustion), it recommends containment and evidence preservation first.\n- **Access mapping** — asks once what evidence sources exist, then continues immediately. Code-only is valid.\n- **Fact / Inference / Unknown** — separates observed production facts from code-only reasoning. Never presents an inference as a fact.\n- **Bug chain** — traces `trigger → first invalid state → propagation → visible symptom`, citing concrete code at every link.\n- **Signal hierarchy** — builds the strongest available reproduction loop: red test > production evidence loop > surrogate fixture > static-only analysis. Static-only lowers confidence but does not block.\n- **Falsifiable hypotheses** — generates 3-5 hypotheses before editing, each with a prediction and a cheapest probe. Uses parallel read-only investigators when supported.\n- **Surgical probes** — every probe maps to a prediction. Bounded, human-run, read-only production requests with explicit scope, safety, and return shape.\n- **Regression test before fix** — locks the bug down at the closest truthful seam, then applies the smallest patch that repairs the earliest violated invariant.\n- **Adversarial verification** — reruns the strongest signal, challenges the result, and reports local verification separately from production verification.\n- **No symptom hiding** — rejects catch-alls, silent defaults, broad retries, and larger timeouts unless that behavior is the explicit contract.\n\n## Install\n\n```bash\n# global, all projects\ngit clone https://github.com/cskwork/debug-code-skill ~/.claude/skills/debug-code\n\n# this project only\ngit clone https://github.com/cskwork/debug-code-skill .claude/skills/debug-code\n```\n\nThe folder name and frontmatter name must remain `debug-code`.\n\n## Use\n\nInvoke it explicitly or describe a concrete production symptom, error, intermittent failure, performance regression, or focused suspected legacy path. Example:\n\n```text\n/debug-code Production returns duplicate invoices after a worker retry. We have code,\nGrafana, dev DB, and can ask an operator to run a bounded read-only MySQL query.\n```\n\nThe skill works in code-only mode. Additional access improves proof strength but is not assumed.\n\n## Package\n\n```text\ndebug-code/\n├── SKILL.md\n├── references/\n│   ├── production-probes.md\n│   └── production-bug-patterns.md\n└── evals/\n    └── trigger-cases.md\n```\n\n## Design references\n\n- Matt Pocock, `diagnosing-bugs`: https://github.com/mattpocock/skills\n- Dietrich Gebert, Ponytail: https://github.com/DietrichGebert/ponytail\n- Remy Sharp, \"The Art of Debugging\": https://remysharp.com/2015/10/14/the-art-of-debugging\n- Google SRE, \"Troubleshooting Methodology\": https://sre.google/sre-book/effective-troubleshooting/\n- OWASP Logging Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 3814,
  "sha": "5063d676e2ef2f84f6d48cff75fc6d50fe5757fd5e4702662572486c93dac37f",
  "repo_slug": "cskwork/debug-code-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cskwork_debug_code_skill_eaada4cc/readme"
}