parallel-debugging skill
✓ VerifiedDebug complex issues by generating competing hypotheses and performing parallel investigation with evidence-based root cause arbitration.
- GitHub stars
- 42,413
- Files
- 2
- Last commit
- Nov 9, 2026
- License
- MIT
- Allowed tools
- —
What does the parallel-debugging skill do?
parallel-debugging is an agent skill. Debug complex issues by generating competing hypotheses and performing parallel investigation with evidence-based root cause arbitration.
Summary generated from the skill's SKILL.md.
About the parallel-debugging skill
Resolving complex software bugs by generating competing hypotheses and conducting parallel investigations is the primary function of this skill. It is designed for developers facing issues with multiple plausible root causes, problems spanning several modules, or situations where initial debugging attempts have failed. By applying the Analysis of Competing Hypotheses methodology, an agent can systematically investigate six failure mode categories including logic errors, data issues, state problems, integration failures, resource issues, and environment discrepancies.
An agent should load this skill when performing systematic root cause analysis to avoid confirmation bias. The process produces structured evidence categorized by strength, such as direct, correlational, testimonial, or absence of data. The skill relies on a strict citation format using file and line references to maintain high confidence levels. Once investigations are complete, the tool uses a result arbitration protocol to categorize findings as confirmed, plausible, falsified, or inconclusive, ultimately helping to determine if a single root cause or a compound issue exists.
What an agent can do with it
- 1Investigate multi-module system failuresAnalyze a bug that spans across different components by generating hypotheses across various failure categories.
- 2Mitigate developer confirmation biasSystematically evaluate different potential causes of a bug to ensure the investigation remains objective.
- 3Perform evidence-based root cause arbitrationCompare multiple confirmed hypotheses to identify the most likely cause of a system error.
- 4Validate a software fixEnsure that a proposed solution actually addresses the identified root cause without creating new problems.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the parallel-debugging skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the parallel-debugging skill in Plugin
/plugin marketplace add wshobson/agents /plugin install agent-teams@claude-code-workflows
Install the parallel-debugging skill in Claude Code
~/.claude/skills/parallel-debugging/SKILL.md
$ npx degit wshobson/agents/plugins/agent-teams/skills/parallel-debugging ~/.claude/skills/parallel-debuggingInstall the parallel-debugging skill in Claude Code (project)
.claude/skills/parallel-debugging/SKILL.md
$ npx degit wshobson/agents/plugins/agent-teams/skills/parallel-debugging .claude/skills/parallel-debuggingInstall the parallel-debugging skill in Codex
~/.agents/skills/parallel-debugging/SKILL.md
$ npx degit wshobson/agents/plugins/agent-teams/skills/parallel-debugging ~/.agents/skills/parallel-debuggingInstall the parallel-debugging skill in Gemini CLI
~/.gemini/skills/parallel-debugging/SKILL.md
$ npx degit wshobson/agents/plugins/agent-teams/skills/parallel-debugging ~/.gemini/skills/parallel-debuggingInstall the parallel-debugging skill in Claude.ai
npx degit wshobson/agents/plugins/agent-teams/skills/parallel-debugging parallel-debugging && zip -r parallel-debugging.zip parallel-debugging # claude.ai → Customize → Skills → + → Create skill → Upload a skill → parallel-debugging.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablewshobson/agents/plugins/agent-teams/skills/parallel-debugging is public and reachablegithub.com/wshobson/agents/tree/HEAD/plugins/agent-teams/ski ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/wshobson/agents/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/wshobson/agents/blob/HEAD/plugins/agent-teams/ski ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/wshobson/agents/blob/HEAD/plugins/agent-teams/ski ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 134 linesgithub.com/wshobson/agents/blob/HEAD/plugins/agent-teams/ski ↗Pass
SKILL.md
View on GitHubParallel 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
Files in this skill
2parallel-debugging skill questions
How do I install the parallel-debugging skill in Claude Code?
Run npx degit wshobson/agents/plugins/agent-teams/skills/parallel-debugging ~/.claude/skills/parallel-debugging. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the parallel-debugging skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
When should I use the parallel debugging skill?
Use this skill when a bug has multiple plausible root causes, initial debugging has failed, the issue spans multiple components, or you need a systematic root cause analysis.
How is evidence strength categorized?
Evidence is categorized into Direct (Strong), Correlational (Medium), Testimonial (Weak), and Absence (Variable).