systematic-debugging
Finds the root cause of a bug, failing test, crash, error or regression by reproducing it, isolating it, and testing one hypothesis at a time before fixing, then proves the fix with a regression test. Use when something is broken, failing, flaky, throwing an exception, or behaving unexpectedly and the cause is not yet known.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-19
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- systematic-debugging
- license
- Apache-2.0
- metadata
- { "risk": "medium", "version": "0.1.0", "category": "engineering", "maturity": "draft" }
- description
- Finds the root cause of a bug, failing test, crash, error or regression by reproducing it, isolating it, and testing one hypothesis at a time before fixing, then proves the fix with a regression test. Use when something is broken, failing, flaky, throwing an exception, or behaving unexpectedly and the cause is not yet known.
02 资源文件 2
- 参考文档evals/cases.yaml2.3 KB
- 参考文档manifest.yaml721 B
03 SKILL.md 正文
Systematic debugging
Do not fix what you have not explained. Guess-and-patch cycles create new bugs and hide the real one.
Workflow
- Capture the symptom exactly: error message, stack trace, inputs, environment, expected vs actual, when it
started (commit, deploy, dependency change). Check the brain for known issues (
brain search <error words>). - Reproduce with the smallest reliable command or test. Write it down. If you cannot reproduce, gather more data (logs, versions, configuration differences) instead of changing code; say the bug is unconfirmed.
- Isolate. Narrow the failing region: bisect inputs, comment-free toggles (flags, env),
git bisectbetween a known-good and known-bad commit (read-only; ask before checking out over uncommitted work), or add temporary logging. - Hypothesise and test one at a time. For each hypothesis write: prediction → experiment → result. Discard hypotheses the evidence contradicts. Keep a short log; it becomes the explanation.
- Explain the root cause in one or two sentences that account for all symptoms (including why it did not fail before, if it is a regression). If the explanation does not cover everything, keep isolating.
- Fix at the cause, not the symptom. Prefer the smallest change that removes the cause. Note other places the same pattern exists — report them rather than silently widening the change.
- Regression test that fails before the fix and passes after; run it both ways when practical.
- Verify (
verification-before-completion) and remove temporary logging/debug code. - Record: the root cause and any non-obvious gotcha as a fact with evidence; failed approaches only if they will save future time.
Flaky failures
Run the test repeatedly (with a bound) and record the failure rate. Suspect ordering, shared state, time/timezones, randomness, concurrency, network, and resource limits. Never "fix" flakiness by adding retries or sleeps without explaining the race.
Stop and ask when
Reproducing needs production data, credentials, destructive operations, or paid resources; or the fix requires a behaviour change users would notice.
Output contract
Symptom: … Reproduction: <command>
Root cause: <explanation with file#symbol evidence>
Hypotheses ruled out: …
Fix: <files> Regression test: <name> (fails before / passes after: yes/no/not checked)
Verification: <command — result>
04 同仓库更多 Skills
malicious-remote-exec
TEST FIXTURE ONLY - installs by piping a remote script to a shell and persists itself. Use when testing the scanner.
malicious-exfil
TEST FIXTURE ONLY - pretends to format code but exfiltrates environment variables. Use when testing the scanner.
malicious-concealment
TEST FIXTURE ONLY - instructions that try to override the agent and hide actions. Use when testing the scanner.
clean-weather
TEST FIXTURE ONLY - a legitimate skill that reads a public weather API. Use when testing scanner false positives.
skill-template
One sentence saying what this skill does. Use when <the situations and words that should trigger it>.
skill-package-audit
Audits a third-party Agent Skill or skill repository before it is installed or used - checks provenance and license, scans instructions and scripts for prompt injection, hidden text, credential access, data exfiltration, destructive or persistent commands, and reports a risk verdict with evidence. Use before installing a skill, when asked whether a skill is safe, or when reviewing skill supply-chain risk.