parallel-debugging

Use it when:: A bug has several plausible causes, first attempts failed, or it spans several modules and you want to avoid fixing the first theory that fits.
It does:: Draws hypotheses from six failure types, has investigators gather evidence for each, then sorts them into confirmed, plausible, falsified or inconclusive.
You get:: A root cause backed by file:line evidence and a confidence level, a compound cause, or new hypotheses when none holds up.
Terms:: Analysis of Competing Hypotheses (ACH) tests several explanations side by side instead of chasing one.

TL;DR

A method for running several lines of investigation at once, written for a team of agents, though it names no particular tool. Hypotheses come from six failure categories: logic errors, data issues, state problems such as races and stale caches, integration failures, resource exhaustion and environment differences. Evidence is graded as direct (the code at a line), correlational (errors rose after a commit), testimonial ("works on my machine") or absence (no null check on the path), and is always cited with file:line. Confidence is high above 80%, with several direct pieces and nothing contradicting, medium from 50% and low below. Once every investigator reports, each hypothesis is labelled confirmed, plausible, falsified or inconclusive, and confirmed ones are ranked by confidence, amount of evidence, strength of the causal chain and lack of contradiction. One clear winner is the root cause, a tie may be a compound issue, and no winner means new hypotheses from what was learned. Before the bug counts as fixed, the fix must address the root cause, break nothing new, pass the original reproduction, cover related edge cases and come with tests.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill parallel-debugging

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 10,400 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Feb 5, 2026 on skills.sh

Weekly Downloads

158

-16% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	189
Sep 28	221
Oct 5	268
Oct 12	216
Oct 19	187
Oct 26	185
Nov 2	171
Nov 9	158

Category	category:debugging category:agents category:software-engineering Find root causes, review code and test what you built. Build agents, orchestrate workers and give agents memory. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:workflow A multi-step process the agent follows: interview, debug, run a TDD loop, review.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:subagents Relies on the agent being able to spawn subagents.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	debugging multi-agent

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

name: parallel-debugging
description: 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.
version: 1.0.2

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:

Confidence level
Number of supporting evidence pieces
Strength of causal chain
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