Skills systematic-debugging
📦

systematic-debugging

Content revision r1 Medium Risk ⚙️ External commands📁 Filesystem access🔑 Env variables

Debug Root Causes Systematically

Random fixes waste time and often create new defects. This skill guides Claude, Codex, and Claude Code through evidence gathering, hypothesis testing, and verified fixes.

Supports: Claude Codex Code(CC)
📊 71 Adequate

Install with my Agent

Copy this request to your Agent. It includes the canonical Skill page and manifest.

Agent request
Review the Skillstore skill "systematic-debugging" from https://skillstore.io/skills/obra-systematic-debugging.md and its manifest at https://skillstore.io/api/skills/obra-systematic-debugging/manifest. Verify the artifact. You may proceed after verification, subject to the environment's own policy.

Your Agent should still show its plan and request any confirmation required by the security policy.

Agent-readable resources

Use these links when an AI agent, crawler, or script needs clean context instead of reading the full page.

Markdown detail GET /skills/obra-systematic-debugging.md Signed manifest GET /api/skills/obra-systematic-debugging/manifest Signed lockfile GET /api/skills/obra-systematic-debugging/lockfile

Test it

Using "systematic-debugging". A payment status test sometimes receives pending instead of completed.

Expected outcome:

  • The response should first document the exact failure and reproduction pattern.
  • It should identify missing evidence about the status transition and async boundary.
  • It should propose one hypothesis and one minimal verification step before any fix.

Using "systematic-debugging". A command created a .git directory in the source tree during tests.

Expected outcome:

  • The response should trace the directory value through each caller.
  • It should find where an empty or wrong path was introduced.
  • It should recommend fixing the source and adding validation at multiple layers.

Using "systematic-debugging". A flaky test uses several fixed sleep calls.

Expected outcome:

  • The response should name the condition the test actually needs.
  • It should replace sleeps with polling that has a timeout and clear error message.
  • It should keep true timing checks only when the timing behavior is the subject of the test.

Security Audit

Medium Risk
v8 • 7/5/2026 Open versioned report

Most static findings are false positives caused by Markdown code fences, TypeScript template literals, ordinary NODE_ENV checks, and prose examples. One instructional diagnostic block is a real medium-risk concern because it can place environment and signing identity details into logs.

11
Files scanned
1,262
Lines analyzed
1
Review items
0
False positives ignored

Confirmed security concerns (1)

Medium
SKILL.md:90-105
Diagnostic Logging Can Expose Signing and Environment Details
The troubleshooting example recommends printing environment variables that match IDENTITY and listing macOS keychain signing identities. In CI or shared logs, this can disclose sensitive build and signing metadata even without network exfiltration.
The cited bash block directly shows env filtering and keychain identity enumeration. The guidance is diagnostic rather than malicious, so confidence is high for exposure risk but not for malicious intent.
Capability review items (1)

These are real local capabilities that may be expected for this skill, so they require review but are not counted as confirmed malicious behavior.

Medium
SKILL.md:90-106
Ruby/shell backtick execution
```bash
The cited bash example instructs running env, security, and codesign diagnostics during troubleshooting. The commands are instructional rather than hidden, but they can expose environment and signing identity details in logs.

Risk Factors

⚙️ External commands (20)
condition-based-waiting-example.ts:36 condition-based-waiting-example.ts:79 condition-based-waiting-example.ts:128 condition-based-waiting.md:74-80 defense-in-depth.md:31-34 defense-in-depth.md:34-38 defense-in-depth.md:64-70 find-polluter.sh:22 find-polluter.sh:23 find-polluter.sh:30 SKILL.md:18-20 SKILL.md:20-77 SKILL.md:77-87 SKILL.md:87-90 SKILL.md:90-106 SKILL.md:106-114 SKILL.md:114-179 SKILL.md:179-282 SKILL.md:282-283 SKILL.md:283-284
📁 Filesystem access (3)
condition-based-waiting.md:55 CREATION-LOG.md:7 find-polluter.sh:42
🔑 Env variables (4)
defense-in-depth.md:58 defense-in-depth.md:58 root-cause-tracing.md:77 root-cause-tracing.md:77
Audited by: codex View Audit History →
Share & cite this report

Share the versioned assessment report, neutral badge, embed card, and citations. Skillstore reports evidence without deciding whether this Skill is safe.

Open versioned report
Security Assessment

Copy report link

https://skillstore.io/skills/obra-systematic-debugging/audits/8?utm_source=security_passport&utm_medium=share&utm_campaign=versioned_report

Markdown badge

[![Skillstore security assessment](https://skillstore.io/badges/skills/obra-systematic-debugging/security.svg)](https://skillstore.io/skills/obra-systematic-debugging?utm_source=security_passport_badge)

HTML badge

<a href="https://skillstore.io/skills/obra-systematic-debugging?utm_source=security_passport_badge"><img src="https://skillstore.io/badges/skills/obra-systematic-debugging/security.svg" alt="Skillstore security assessment" loading="lazy"></a>

Embed card

<iframe src="https://skillstore.io/embed/skills/obra-systematic-debugging.html" title="Skillstore Security Assessment" sandbox="allow-popups allow-popups-to-escape-sandbox" loading="lazy" referrerpolicy="no-referrer" width="420" height="180"></iframe>
Academic citations (APA · BibTeX · CFF)

APA citation

obra. (2026). systematic-debugging security audit report (audit version 8) [Author version unspecified]. Skillstore. https://skillstore.io/skills/obra-systematic-debugging/audits/8

BibTeX citation

@techreport{obra-obra-systematic-debugging-2026, author = {obra}, title = {systematic-debugging security audit report (audit version 8)}, institution = {Skillstore}, year = {2026}, number = {8}, url = {https://skillstore.io/skills/obra-systematic-debugging/audits/8}, note = {Author version unspecified} }

CITATION.cff

cff-version: 1.2.0 message: "If you use this Skill, cite its author and this versioned security audit report." title: "systematic-debugging security audit report (audit version 8)" version: "unspecified" type: report authors: - name: "obra" date-released: "2026-07-05" url: "https://skillstore.io/skills/obra-systematic-debugging/audits/8" identifiers: - type: other value: "skillstore:obra-systematic-debugging:audit:8" description: "Skillstore immutable audit report identifier"

Compare variants

12 installable variants

Each author remains a separate installable skill. The recommended variant is ranked by Skillstore evidence.

Why this variant is first

Highest Skillstore Score
Asmayaseen Recommended

asmayaseen-systematic-debugging

Skillstore Score 81
Evidence Confidence High
Skillstore usage 20
Updated

2026-08-21

ChrisWiles

chriswiles-systematic-debugging

Skillstore Score 79
Evidence Confidence High
Skillstore usage 11
Updated

2026-08-21

Doyajin174

doyajin174-systematic-debugging

Skillstore Score 79
Evidence Confidence High
Skillstore usage 9
Updated

2026-08-21

DMJGilbert

dmjgilbert-systematic-debugging

Skillstore Score 79
Evidence Confidence High
Skillstore usage 9
Updated

2026-08-21

CodingCossack

codingcossack-systematic-debugging

Skillstore Score 74
Evidence Confidence High
Skillstore usage 59
Updated

2026-08-21

ZhanlinCui

zhanlincui-systematic-debugging

Skillstore Score 71
Evidence Confidence High
Skillstore usage 90
Updated

2026-08-21

obra Current

obra-systematic-debugging

Skillstore Score 71
Evidence Confidence High
Skillstore usage 14
Updated

2026-08-21

Cycleaddict

cycleaddict-systematic-debugging

Skillstore Score 71
Evidence Confidence High
Skillstore usage 5
Updated

2026-08-21

davila7

davila7-systematic-debugging

Skillstore Score 70
Evidence Confidence High
Skillstore usage 5
Updated

2026-08-21

DYAI2025

dyai2025-systematic-debugging

Skillstore Score 70
Evidence Confidence Medium
Skillstore usage 45
Updated

2026-08-21

Cygnusfear

cygnusfear-systematic-debugging

Skillstore Score 50
Evidence Confidence High
Skillstore usage 5
Updated

2026-08-21

sickn33

sickn33-systematic-debugging

Skillstore Score 38
Evidence Confidence Medium
Skillstore usage 12
Updated

2026-08-21

Skillstore Score

Why this score Evidence Confidence: High
55
Architecture
85
Maintainability
87
Content
71
Community
91
Spec Compliance

What You Can Build

Investigate Failing Tests

Use the workflow to reproduce failures, compare working examples, and test one hypothesis at a time.

Stabilize Flaky Automation

Replace arbitrary sleeps with condition-based waiting and identify the state that tests should observe.

Guide Incident Debugging

Structure evidence gathering during outages while separating immediate mitigation from root-cause repair.

Try These Prompts

Start a Bug Investigation 
Use systematic-debugging for this failure. First list the observed error, reproduction steps, recent changes, and missing evidence before suggesting any fix.
Analyze a Test Failure 
Apply the four debugging phases to this failing test. Identify the root-cause hypothesis, the smallest test for it, and the verification command.
Trace Bad Data Backward 
Use root-cause tracing for this invalid value. Walk backward through callers, record where the value changes, and stop only at the original trigger.
Recover After Failed Fixes 
Three attempted fixes failed. Use systematic-debugging to re-evaluate the architecture, list evidence for each failed hypothesis, and propose the next investigation step.

Best Practices

  • Gather reproducible evidence before proposing a code change.
  • Test one hypothesis with the smallest possible change.
  • Verify the final fix with the failing case and relevant regression tests.

Avoid

  • Adding a quick workaround before understanding the failure path.
  • Changing several variables at once and then guessing which one helped.
  • Treating repeated failed fixes as implementation trouble instead of a signal to re-analyze.

Frequently Asked Questions

When should I use this skill?
Use it for bugs, failing tests, unexpected behavior, build failures, performance issues, and integration problems.
Does it make the agent slower?
It adds investigation steps, but it reduces wasted time from repeated guesses and unstable fixes.
Can it help during production incidents?
Yes, but urgent mitigation may come first. Use the process to keep evidence and root-cause repair separate.
Does it run commands automatically?
No. It provides process guidance and examples. Any command execution depends on the agent and user environment.
What should I avoid with the included examples?
Do not print secrets, keychain data, or sensitive environment values into shared logs.
Which tools can use it?
The report lists support for Claude, Codex, and Claude Code.

Developer Details

Author

obra

License

MIT

Skillstore revision

r1

Version notice

The author did not declare a version.

Repository

https://github.com/obra/superpowers/tree/main/skills/systematic-debugging

Ref

62e2a730c5cd74eab4c7164309d810de660fcea3

Maintenance freshness

7/18/2026

Usage

12 downloads · 288 views

File structure

📄 condition-based-waiting-example.ts

📄 condition-based-waiting.md

📄 CREATION-LOG.md

📄 defense-in-depth.md

📄 find-polluter.sh

📄 root-cause-tracing.md

📄 SKILL.md

📄 test-academic.md

📄 test-pressure-1.md

📄 test-pressure-2.md

📄 test-pressure-3.md