parallel-debug

Parallel Debug Workflow

This skill is the orchestrator. It owns everything the individual agents (hypothesis-investigator, hypothesis-arbitrator) do not: session setup, isolation, collecting reports, deciding whether arbitration is even needed, applying the final result, and cleaning up afterward.

When to Use

Use parallel-debug when:

• The root cause is genuinely unclear (multiple plausible theories coexist)
• The bug is intermittent or hard to reproduce consistently
• A previous sequential debug pass was inconclusive
• Time pressure demands concurrent investigation over sequential elimination

For bugs with an obvious root cause, a direct sequential investigation is faster and uses fewer resources. This is a development-phase tool only — it never runs against a production environment. See the plugin README's "When NOT to Use" section for the full list of cases where a manual investigation beats this workflow (simple bugs, heavy test environments, tight deadlines).

---

Step 0 — Session setup

1. Create a session directory: .claude/debug-sessions/{session_id}/ where session_id is a short timestamp-based slug (e.g. 20260701-1432). If the project's .gitignore does not already exclude .claude/debug-sessions/, tell the user to add it — otherwise session directories and reports show up as untracked files in git status. "No uncommitted changes" in step 2 refers only to tracked files; untracked leftover session directories from a prior run do not block a new session, but should still be cleaned up if stale.
2. Confirm the repo has no uncommitted changes to tracked files on the current branch before proceeding. If it does, ask the user whether to stash them first — do not silently stash or discard user work.
3. Record the base commit SHA in .claude/debug-sessions/{session_id}/base.txt. Every investigator worktree and the final patch application will be diffed against this SHA.
4. Read .claude/debugging-workflow.local.md if it exists. Parse the YAML frontmatter:
   • max_parallel_agents — integer 2–5, default 4; caps how many hypothesis-investigator agents run concurrently (see the batching rule in Step 3), independent of hypothesis_count
   • time_budget_minutes — integer 1–15, default 5, approximate time budget per agent (agents run in parallel, so this is not a total)
   • hypothesis_count — integer 2–4, default 3
   • preflight_max_minutes — integer, default 5; wall-clock cap for item 5 below
   • degraded_mode — boolean, default false; forces the single-worktree, sequential-hypothesis execution path in Steps 2/3/7 — see references/resource-constraints.md