tools-only /zerg:debug
Deep diagnostic investigation for ZERG execution issues with error intelligence, log correlation, hypothesis testing, and code-aware recovery.
Synopsis
/zerg:debug [PROBLEM_DESCRIPTION]
[--feature <name>] [-f <name>]
[--worker <id>] [-w <id>]
[--deep]
[--fix]
[--error <msg>] [-e <msg>]
[--stacktrace <path>] [-s <path>]
[--env]
[--interactive] [-i]
[--report <path>]
Description
The debug command performs systematic diagnosis of ZERG execution failures. It follows a multi-phase investigation pipeline that gathers context, classifies symptoms, collects evidence, tests hypotheses using Bayesian probability scoring, determines root causes, and generates recovery plans.
If PROBLEM_DESCRIPTION is provided as plain text (without flags), it is treated as a free-form description of the problem to investigate.
Investigation Phases
- Context Gathering -- Read ZERG state, logs, task graph, design documents, and git state in parallel.
- Error Intelligence -- Multi-language error parsing, fingerprinting, chain analysis, and semantic classification.
- Symptom Classification -- Classify into one category:
WORKER_FAILURE,TASK_FAILURE,STATE_CORRUPTION,INFRASTRUCTURE,CODE_ERROR,DEPENDENCY,MERGE_CONFLICT, orUNKNOWN. - Log Correlation -- Timeline reconstruction, temporal clustering, cross-worker correlation, and error evolution tracking.
- Evidence Collection -- Category-specific evidence checklists.
- Hypothesis Testing -- Bayesian probability scoring with a maximum of 3 hypotheses and automated test commands.
- Root Cause Determination -- Synthesize findings into a root cause statement with a confidence level.
- Recovery Plan -- Code-aware fix suggestions with risk levels:
[SAFE],[MODERATE], or[DESTRUCTIVE]. When--fixis used, each step requires confirmation before execution. - Design Escalation Check -- If issues require architectural changes, recommend running
/zerg:design. - Report -- Save a diagnostic report to
claudedocs/debug-<timestamp>.mdor the path specified by--report. - Environment Diagnostics -- When
--envis set, run Python, Docker, system resource, and config validation checks.
Feature Detection
If --feature is not provided, the command auto-detects the active feature from .gsd/.current-feature.
Options
| Option | Short | Default | Description |
|---|---|---|---|
--feature |
-f |
auto-detected | Feature name to investigate. |
--worker |
-w |
all | Focus investigation on a specific worker ID. |
--deep |
-- | off | Run system-level diagnostics including git, disk, Docker, ports, and worktrees. |
--fix |
-- | off | Generate and execute a recovery plan with per-step confirmation. |
--error |
-e |
-- | A specific error message to analyze. |
--stacktrace |
-s |
-- | Path to a stack trace file to include in analysis. |
--env |
-- | off | Run comprehensive environment diagnostics (Python venv, packages, Docker, resources, config validation). |
--interactive |
-i |
off | Interactive debugging wizard mode for guided step-by-step diagnosis. |
--report |
-- | claudedocs/debug-<timestamp>.md |
Write the full diagnostic report to the specified path. |
Examples
Investigate a general problem described in plain text:
/zerg:debug workers keep crashing
Debug a specific feature:
/zerg:debug --feature user-auth
Focus on a single worker:
/zerg:debug --worker 3
Run deep system-level diagnostics:
/zerg:debug --deep
Diagnose and attempt recovery:
/zerg:debug --fix
Analyze a specific error message:
/zerg:debug --error "ModuleNotFoundError: No module named 'zerg.launcher'"
Run environment diagnostics:
/zerg:debug --env
Save the report to a custom path:
/zerg:debug --report claudedocs/auth-debug.md
Symptom Categories
| Category | Description |
|---|---|
WORKER_FAILURE |
Worker process crashed or exited unexpectedly. |
TASK_FAILURE |
Task verification command failed. |
STATE_CORRUPTION |
Inconsistency between task system and state JSON. |
INFRASTRUCTURE |
Docker, port, disk, or network issues. |
CODE_ERROR |
Syntax, import, or runtime errors in generated code. |
DEPENDENCY |
Missing or incompatible dependency. |
MERGE_CONFLICT |
Git merge conflicts between worker branches. |
UNKNOWN |
Cannot classify; requires manual investigation. |
Recovery Risk Levels
| Level | Meaning |
|---|---|
[SAFE] |
No risk of data loss. Can be applied without concern. |
[MODERATE] |
Some risk. Review the suggested change before applying. |
[DESTRUCTIVE] |
Potential data loss. Requires explicit confirmation and a backup. |
Task Tracking
This command creates a Claude Code Task with the subject prefix [Debug] on invocation. If a design escalation is detected, the suffix DESIGN ESCALATION is appended to the task subject. The task is updated to in_progress immediately and marked completed after the report is saved.
See Also
- [[zerg-worker]] -- Worker execution protocol and failure handling
- [[zerg-plugins]] -- Plugin system for custom quality gates and hooks
- [[zerg-build]] -- Rebuild after applying fixes
- [[zerg-test]] -- Re-run tests to verify fixes