systematic-debugging

A four-stage method for debugging software: reproduce the problem, narrow down where it occurs, find the root cause, and verify a focused fix.

In plain words
What is it for?
Use it to investigate errors, intermittent failures, boundary cases, timing problems, configuration mistakes, and dependency conflicts.
Why use it?
It replaces guesswork and random edits with evidence from repeatable tests, code inspection, logs, and recent changes.

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/nikolahuang/nova-cli/systematic-debugging
Any agent
npx skills add Nikolahuang/nova-cli --skill systematic-debugging
Clone the repo
git clone --depth 1 https://github.com/Nikolahuang/nova-cli

Made for: Claude Code, Codex.

Per session 31 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 806 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.00031 $0.00806
Opus 5 $0.00015 $0.00403
Sonnet 5 $0.00006 $0.00161
Haiku 4.5 $0.00003 $0.00081

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

Security

Grade A, and why

systematic-debugging 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.

extensions/skills/systematic-debugging/SKILL.md · 110 lines

What it actually says

系统化调试 - 4 阶段根因分析

概述

使用结构化的 4 阶段流程系统化地找出并修复 bug,而不是靠猜测。

阶段 1: 复现和理解

复现问题

  • 记录确切的复现步骤
  • 确定是否可稳定复现
  • 记录环境信息(OS、版本、配置)
  • 记录错误消息和堆栈跟踪

理解期望行为

  • 期望发生什么?
  • 实际发生了什么?
  • 差异是什么?

收集信息

  • 使用 read_file 查看相关代码
  • 使用 search_content 查找相关逻辑
  • 使用 execute_command 运行诊断命令

阶段 2: 隔离

缩小范围

  • 二分法:哪一半代码有问题?
  • 注释掉代码块,看问题是否消失
  • 创建最小复现示例

检查边界

  • 输入边界(空值、最大值、最小值)
  • 状态边界(初始化、中间、结束)
  • 时间边界(竞态、超时)

验证假设

  • 每次只改变一个变量
  • 记录每次测试的结果
  • 不要同时修复多个问题

阶段 3: 根因分析

5 个为什么

对每个发现问"为什么",深入到根本原因:

问题: X 发生了
为什么? → 因为 Y
为什么? → 因为 Z
为什么? → 因为 [根本原因]

常见根因模式

  • 状态错误: 变量值不正确
  • 时序问题: 竞态、死锁
  • 边界遗漏: 未处理边界情况
  • 配置错误: 配置不匹配
  • 依赖问题: 版本不兼容

根因追踪技术

  • 添加日志追踪变量值
  • 使用调试器逐步执行
  • 检查最近的代码变更

阶段 4: 修复和验证

修复原则

  • 最小化改动 - 只修改必要的
  • 不引入新功能
  • 保持代码风格一致

验证修复

  1. 原问题是否修复?
  2. 是否引入新问题?
  3. 边缘情况是否处理?
  4. 相关测试是否通过?

深度防御

  • 添加验证和断言
  • 添加错误处理
  • 记录限制和假设

文档化

  • 记录问题原因
  • 记录修复方案
  • 更新相关文档

调试反模式

避免这些:

  • ❌ 随机修改代码看效果
  • ❌ 复制粘贴修复而不理解
  • ❌ 忽略偶发问题
  • ❌ 同时修改多处

关键原则

  • 系统化 - 有条理地排除可能性
  • 证据驱动 - 基于证据而非猜测
  • 一次一个变量 - 控制变量
  • 记录过程 - 便于回溯和学习
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 · 110 lines · 31 tokens per session scan A 677c1a6eaaa9

Subscribe to this mod's changes

systematic-debugging is a skill published in the GitHub repository Nikolahuang/nova-cli (14 stars, last pushed 4mo ago), licensed MIT. It adds 31 tokens to every session and 806 once invoked, about $0.0002 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-30.

Related

Other skills, from other repositories

a0-debug-plugin

Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving…

agent0ai/agent-zero · 68 tokens

debugging

Debugging your dating life — debug bad matches, debug miscommunication, and debug your profile for better connections. Debugging compatibility, debugging conversations, and debugging relationships on inbed.ai. 调试、修复。Depuración, arreglar citas.

geeks-accelerator/in-bed-ai · 53 tokens

a0-debug-plugin

Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving…

Gen-Verse/PAST-Bench · 68 tokens

troubleshooting

Skill "troubleshooting" from chaterm/terminal-skills, covering kubernetes 故障排查, 概述, 集群状态检查, 节点状态 and 查看节点.

chaterm/terminal-skills · 11 tokens

quarkus-debug

Expert skill for deep debugging of Quarkus applications, covering Dev Mode, Reactive patterns (Mutiny), Native Image (AOT) issues, and Build-time (Augmentation) troubleshooting.

kinhluan/rules-quarkus-skills · 43 tokens

Debugging

Systematic root-cause isolation and minimal fix proposal for software bugs.

Tariux/AI-Skills-Not-Awesome · 17 tokens