systematic-debug

A structured debugging process for investigating bugs, errors, failed tests, and unexpected behavior. It starts by creating a quick, repeatable way to reproduce the problem before testing possible causes.

In plain words
What is it for?
It is for debugging failing tests, stack traces, HTTP 500 errors, broken features, and situations where software suddenly stops working.
Why use it?
It prevents guesswork and small fixes that only hide the symptom. Reproducing the failure gives the agent a clear signal for checking whether the real cause was addressed.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/skymanbp/cc-enforcer/systematic-debug
Any agent
npx skills add skymanbp/cc-enforcer --skill systematic-debug
Clone the repo
git clone --depth 1 https://github.com/skymanbp/cc-enforcer

Made for: Claude Code, Codex.

Per session 119 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 3,275 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00119 $0.03275
Opus 5 $0.00060 $0.01638
Sonnet 5 $0.00024 $0.00655
Haiku 4.5 $0.00012 $0.00328

Measured 2d ago against content hash f5678c32b5f2, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

systematic-debug scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/systematic-debug/SKILL.md · 165 lines

How it starts

The opening of the file, as written. The whole thing — 165 lines — stays where its author put it; the contents beside it link to each section on GitHub.

systematic-debug — 系统式 debug 流程

你(主代理)已被本 skill 接管。在解决用户描述的问题前,必须按以下流程进行根因分析。 这个 skill 是 rules/02-systematic-not-reactive.mdrules/03-root-cause.md 的强制执行入口。

强制流程(按顺序执行,不允许跳步)

Step 0 · 构建可复现信号(feedback loop)

这是本 skill 最核心的一步。 借鉴 mattpocock-skills:diagnose 的 Phase-1 原则: "If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause." 没有可复现信号,后续 Step 3 / Step 4 的"假设 → 证伪"全是空中楼阁——你只能凭印象写"应该是 X"。

未建立可复现信号前,禁止进入 Step 3。 反复试图绕开 Step 0 跳到 Step 3 是本 skill 的高频违规。

0.1 · 选一种 loop 形态(按优先级试 10 种)

按下面顺序尝试,先选满足"快 + 确定 + agent 可跑"三条的最高优先级:

  1. Failing test —— 在合适的层(unit / integration / e2e)写一个最小测试,断言 bug 行为。最佳。
  2. Curl / HTTP script —— 对运行中的 dev server 发请求,把响应跟期望 diff。
  3. CLI invocation + snapshot diff —— 用 fixture 输入跑 CLI,跟已知正确输出 byte-diff。
  4. Headless browser 脚本 —— Playwright / Puppeteer 驱动 UI,断言 DOM / console / network。
  5. Replay captured trace —— 把真实 request / payload / event log 存盘,在隔离环境里重放。
  6. Throwaway harness —— 起一个最小子集(单 service + mocked deps),单函数调用触发 bug 路径。
  7. Property / fuzz loop —— bug 是 "sometimes wrong" 时,跑 1000 个随机输入找失败模式。
  8. Bisection harness —— bug 出现在已知两个状态间(commit / dataset / version)→ "boot at state X, check, repeat" 自动化,让 git bisect run 直接跑。
  9. Differential loop —— 同一输入分别跑 old vs new(或两个 config),diff 输出。
  10. HITL bash 脚本 —— 最后兜底;若必须人手点击,至少用脚本驱动人,捕获输出回喂给你。

0.2 · 把 loop 当成产品迭代

选定后立即问:

  • 能不能更快?(缓存 setup、跳无关 init、缩窄测试范围)
  • signal 能不能更尖锐?(断言具体症状,而不是"没崩")
  • 能不能更确定?(pin 时间、seed RNG、isolate fs、freeze network)

30 秒间歇 flaky loop 比没 loop 强不了多少;2 秒确定 loop 就是 debug 超能力。

0.3 · 非确定性 bug:提高复现率而不是要"干净 repro"

50% flake 可 debug;1% 不可。Loop 触发器 100×、并行、加压、缩窄时间窗、注入 sleep——把命中率拉高到能 debug 为止。目标不是 "能必定复现",是 "够频繁能落到 trace"。

0.4 · 真的造不出 loop —— 显式停下

不允许"造不出 loop 就直接猜"。必须:

  • 列出已尝试的 loop 形态 + 各自失败原因
  • 向用户索取:(a) 能复现的环境访问,或 (b) 抓到的 artifact(HAR / log dump / core dump / 带时间戳的录屏),或 (c) 在生产临时加 instrumentation 的授权
  • 绝对禁止:在没 loop 的状态下进 Step 3 假设根源——这等于规则 01 "凭印象断言" 的违规。

Read the full file on GitHub · 165 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 165 lines · 119 tokens per session scan A f5678c32b5f2

Subscribe to this mod's changes

systematic-debug is a skill published in the GitHub repository skymanbp/cc-enforcer (5 stars, last pushed 7d ago), licensed MIT. It adds 119 tokens to every session and 3,275 once invoked, about $0.0006 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

recipe-quality-profile

Proposes repository-specific quality policy for implementation and review and, after confirmation, creates or updates docs/project-context/quality.yaml. Use when asked to create or update a repository quality profile.

shinpr/claude-code-workflows · 41 tokens

brooks-sweep

Full-sweep mode: runs a unified analysis across all quality dimensions — code decay, architecture, tech debt, and test quality — then applies fixes directly to the codebase. Safe changes are auto-applied; risky changes are confirmed before execution. Drawing on twelve classic engineering books. Triggers when: user…

hyhmrright/brooks-lint · 178 tokens

truecourse-fix

Fix TrueCourse violations that have suggested fixes.

truecourse-ai/truecourse · 13 tokens

bestie-features

Add BestieTemplate features (AGENTS.md, changelog, dependabot, pre-commit, lint workflow, testitem runner) to a Julia package with the bestie CLI — no Julia needed. Use when asked to add one of these files/setups to a package, or to see what BestieTemplate can add.

JuliaBesties/BestieTemplate.jl · 71 tokens

laravel-owasp-security

OWASP Top 10 security audit and secure coding guidelines for Laravel + React/Inertia.js applications. Use when auditing for vulnerabilities ("run OWASP audit", "security review", "check my app security") or writing secure Laravel code involving auth, payments, file uploads, or API design. Triggers on security-related…

AsyrafHussin/agent-skills · 87 tokens

sillytavern-overseer

严格监督,高压管理,不容懈怠.

linkerlin/PUAX · 19 tokens