Systematic Debugging

Use when encountering a bug, test failure, performance regression, build failure, integration issue, or unexpected behavior before proposing or applying a fix.

9 stars 3 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add sandbaseai/workbuddy-skill --skill systematic-debugging
Manual install
git clone --depth 1 https://github.com/sandbaseai/workbuddy-skill.git /tmp/workbuddy-skill
mkdir -p ~/.claude/skills
cp -r /tmp/workbuddy-skill/skills/systematic-debugging ~/.claude/skills/systematic-debugging

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Systematic Debugging

用可重复的反馈回路和证据追踪定位根因。核心规则是:在根因调查完成前,不提出“顺手修一下”的补丁;症状修复不能替代根因证据。

## 总原则与安全边界

- 先收集错误、复现、数据流和边界证据,再形成假设;不要用直觉或时间相关性代替调查。
- 默认只读检查代码、配置、日志、提交历史和测试入口;生产数据、共享环境、部署配置和外部服务不因调试而被修改。
- 目标仓库、提交、环境、命令和授权范围必须明确。输出中的命令、日志、请求和抓取工件先脱敏。
- 调试日志、临时 fixture、回放数据和 instrumentation 必须有唯一标记、范围和清理计划,不能包含密钥或客户数据。
- 每次只改变一个变量。若连续三次修复尝试都暴露新问题,停止继续堆补丁,转而评估架构、共享状态和耦合,并单独请求架构决策授权。

## 阶段一:建立红色反馈回路

先建立一个已经运行过、能捕获用户准确症状的命令或测试:优先是失败测试,其次是带断言的 HTTP/CLI、浏览器脚本、受控 trace 回放、最小 harness 或属性测试。它必须:

- 能沿真实代码路径触发该症状,而不是只证明程序没崩;
- 有确定或可量化的失败 verdict,运行时间有界,可无人值守;
- 记录命令、提交、环境、输入摘要、输出、退出码和脱敏证据。

间歇性问题提高复现率并记录样本量、失败频率和时间窗口;无法建立回路时明确写出已尝试项和缺失的日志、HAR、trace、环境或授权,不凭空继续猜测。

## 阶段二:根因调查与数据流追踪

完整读取错误消息、警告和 stack trace,检查相关提交、依赖、配置和环境差异。多组件系统要在每个边界记录输入、输出、配置传播和状态,先确定断点在哪一层,再深入该层。

对于深层错误逆向追踪:坏值从哪里产生?谁把它传入当前函数?上游的哪个转换、默认值、竞态或外部输入首次引入它?持续追踪到第一个可验证的来源,而不是在最后一个报错点加保护分支。

## 阶段三:模式比较

找到同一代码库中可工作的相似路径,与失败路径逐项比较:调用者、输入、配置、依赖版本、状态生命周期、并发、超时和权限。若依赖参考实现,先完整阅读并记录版本与差异;不要因“看起来不相关”而跳过小差异。

## 阶段四:假设和最小测试

形成一个具体、可证伪的假设,例如:“若配置传播是根因,则在边界 B 检查值 X 会观察到缺失;补齐 X 后回路应变绿。”每次只测试一个预测,记录结果和置信度。假设被否定后回到证据阶段,不在原补丁上继续叠加。

测试前可生成 3–5 个候选根因供排序,但不得把候选列表写成已确认结论。每个探针必须对应一个预测;性能问题先建立时间/资源基线,再分析瓶颈。

## 阶段五:修复与回归

根因有证据支持后,在正确的测试 seam 写失败回归测试,先观察它失败,再实施单一根因修复。重新运行最小回路、原始未缩减场景和相关测试,核对没有引入其他回归。没有合适测试 seam 本身就是架构发现,应记录而不是制造虚假覆盖。

修复阶段仍需独立核验:清理 `[DEBUG-...]` 日志和临时 harness,检查差异范围,确认生产或共享环境没有未授权变更,并把已确认根因、证据和未解决风险写入交付说明。

## 交付报告
Read the full skill on GitHub

Details

Skill name
systematic-debugging
Path
skills/systematic-debugging/SKILL.md
License
MIT
Repo updated
8 September 2026

FAQ

What does the Systematic Debugging skill do?

Use when encountering a bug, test failure, performance regression, build failure, integration issue, or unexpected behavior before proposing or applying a fix.

How do I install the Systematic Debugging skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add sandbaseai/workbuddy-skill --skill systematic-debugging. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Systematic Debugging popular?

It lives in sandbaseai/workbuddy-skill, which has 9 GitHub stars and 3 forks.

Related skills

Access Control Security Best Practices

9

sandbaseai/workbuddy-skill

Design, review, implement, and verify least-privilege access controls across users, services, tenants, resources, and administrative workflows.

Security

Accessibility Review

9

sandbaseai/workbuddy-skill

Use when reviewing a web interface or interaction for semantic, keyboard, focus, screen-reader, ARIA, and contrast accessibility risks.

Frontend & Design

Acquire Codebase Knowledge

9

sandbaseai/workbuddy-skill

Use when the user asks to map, document, or onboard into an existing codebase and needs evidence-backed architecture, structure, conventions, integrations, testing, and concerns documentation.

Software Development

Typespec API Operations

9

sandbaseai/workbuddy-skill

Use when adding or reviewing REST operations in a TypeSpec API, including routing, parameters, request/response models, adaptive cards, and confirmations.

Software Development

Source Driven Development

9

sandbaseai/workbuddy-skill

Use when implementing framework- or library-specific behavior where current official documentation, version compatibility, and source citations matter more than memory or generic examples.

Software Development

Using Ost Framework

5

tilmon-engineering/claude-skills

Use when reading or writing OST (Outcome / Strategy / Tactic) graph data in the `agents` TypeDB database - covers the falsifiability rubric, the three-layer discipline, ID conventions, lifecycle transitions, and the structured Task fields that replace generic descriptions

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.