Index of every page on this site: llms.txt
All skills
wshobson avatar

/parallel-debugging

@4220308
by Seth Hobsonwshobson/agents43k stars
4,518
Run it yourself

Debug complex issues using competing hypotheses with parallel investigation, evidence collection, and root cause arbitration. Use this skill when debugging bugs with multiple potential causes, performing root cause analysis, or organizing parallel investigation workflows.

Use this Skill: https://skilld.dev/gh/wshobson/agents/parallel-debugging

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈73 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈822 more on demand in 1 file.

Description uses 3.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈293 characters, or 3.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Parallel Debugging

Framework for debugging complex issues using the Analysis of Competing Hypotheses (ACH) methodology with parallel agent investigation.

When to Use This Skill

  • Bug has multiple plausible root causes
  • Initial debugging attempts haven't identified the issue
  • Issue spans multiple modules or components
  • Need systematic root cause analysis with evidence
  • Want to avoid confirmation bias in debugging

Hypothesis Generation Framework

Generate hypotheses across 6 failure mode categories:

1. Logic Error

  • Incorrect conditional logic (wrong operator, missing case)
  • Off-by-one errors in loops or array access
  • Missing edge case handling
  • Incorrect algorithm implementation

2. Data Issue

  • Invalid or unexpected input data
  • Type mismatch or coercion error
  • Null/undefined/None where value expected
  • Encoding or serialization problem
  • Data truncation or overflow

3. State Problem

  • Race condition between concurrent operations
  • Stale cache returning outdated data
  • Incorrect initialization or default values
  • Unintended mutation of shared state
  • State machine transition error

4. Integration Failure

  • API contract violation (request/response mismatch)
  • Version incompatibility between components
  • Configuration mismatch between environments
  • Missing or incorrect environment variables
  • Network timeout or connection failure

5. Resource Issue

  • Memory leak causing gradual degradation
  • Connection pool exhaustion
  • File descriptor or handle leak
  • Disk space or quota exceeded
  • CPU saturation from inefficient processing

6. Environment

  • Missing runtime dependency
  • Wrong library or framework version
  • Platform-specific behavior difference
  • Permission or access control issue
  • Timezone or locale-related behavior

Evidence Collection Standards

What Constitutes Evidence

Evidence Type Strength Example
Direct Strong Code at file.ts:42 shows if (x > 0) should be if (x >= 0)
Correlational Medium Error rate increased after commit abc123
Testimonial Weak "It works on my machine"
Absence Variable No null check found in the code path

Citation Format

Always cite evidence with file:line references:

**Evidence**: The validation function at `src/validators/user.ts:87`
does not check for empty strings, only null/undefined. This allows
empty email addresses to pass validation.

Confidence Levels

Level Criteria
High (>80%) Multiple direct evidence pieces, clear causal chain, no contradicting evidence
Medium (50-80%) Some direct evidence, plausible causal chain, minor ambiguities
Low (<50%) Mostly correlational evidence, incomplete causal chain, some contradicting evidence

Result Arbitration Protocol

After all investigators report:

Step 1: Categorize Results

  • Confirmed: High confidence, strong evidence, clear causal chain
  • Plausible: Medium confidence, some evidence, reasonable causal chain
  • Falsified: Evidence contradicts the hypothesis
  • Inconclusive: Insufficient evidence to confirm or falsify

Step 2: Compare Confirmed Hypotheses

If multiple hypotheses are confirmed, rank by:

  1. Confidence level
  2. Number of supporting evidence pieces
  3. Strength of causal chain
  4. Absence of contradicting evidence

Step 3: Determine Root Cause

  • If one hypothesis clearly dominates: declare as root cause
  • If multiple hypotheses are equally likely: may be compound issue (multiple contributing causes)
  • If no hypotheses confirmed: generate new hypotheses based on evidence gathered

Step 4: Validate Fix

Before declaring the bug fixed:

  • Fix addresses the identified root cause
  • Fix doesn't introduce new issues
  • Original reproduction case no longer fails
  • Related edge cases are covered
  • Relevant tests are added or updated

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides a safe, structured framework for parallel debugging and root cause analysis using the Analysis of Competing Hypotheses (ACH) methodology. It consists entirely of documentation and templates with no executable code or external dependencies.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    2 files scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 4220308. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 10 months ago
version
1.0.2
  • Debugging
  • root-cause-analysis
  • hypothesis-testing
  • troubleshooting
  • ach
  • parallel-investigation
  • bug-analysis
  • evidence-collection

README badge

README badge for wshobson/agents/parallel-debugging

Organizes parallel investigation of bugs with multiple potential causes using the Analysis of Competing Hypotheses methodology, with structured hypothesis categories, evidence collection standards, and root cause arbitration. Useful for debugging issues spanning multiple modules or when initial attempts haven't identified the problem.

Generated from the current SKILL.md.

How does this skill differ from standard debugging workflows?
It uses the Analysis of Competing Hypotheses (ACH) methodology to systematically generate and test multiple root cause candidates in parallel, rather than pursuing a single suspected cause. This reduces confirmation bias and works well for bugs with unclear origins across multiple modules.
What types of bugs is this skill best for?
Bugs with multiple plausible root causes, issues spanning multiple components or modules, and cases where initial debugging attempts haven't identified the problem. It's less useful for straightforward bugs with an obvious cause.
Do I need to generate hypotheses myself?
No. The skill provides a structured framework with 6 failure mode categories (logic error, data issue, state problem, integration failure, resource issue, environment) to guide hypothesis generation systematically.
How does the skill handle evidence that contradicts a hypothesis?
It evaluates evidence strength (direct, correlational, testimonial, absence) and requires clear citations with file:line references. Contradicting evidence lowers hypothesis confidence or falsifies it during result arbitration.
What if multiple hypotheses are confirmed?
The skill ranks confirmed hypotheses by confidence level, number of supporting evidence pieces, strength of causal chain, and absence of contradicting evidence. Multiple confirmed hypotheses may indicate a compound issue with multiple contributing causes.

Generated from the current SKILL.md. These answers refresh after source changes.