Debug — Root Cause Investigation

Reported current state: $ARGUMENTS

Take the user's current project state (what's broken, errors, symptoms, when it started, recent changes) and return the ROOT CAUSE — the origin where the defect was introduced — backed by concrete evidence. Stop at the diagnosis; do NOT implement a fix.

1. Intake

Parse $ARGUMENTS into: symptom, error text/stack, affected component & scope, timeframe (when it started), recent changes (deploys/commits), reproduction steps.

• If a critical signal is missing (no error text AND no reproduction), ask ONE concise clarifying question before investigating (per Decision Classification in orchestration-protocol.md). Otherwise proceed.

2. Investigate (orchestrate)

Delegate the investigation to the debugger subagent. Instruct it to follow the debugging skill Four-Phase process:

1. Root Cause Investigation — read errors, reproduce, check recent changes, gather evidence.
2. Pattern Analysis — compare against working examples.
3. Hypothesis & Testing — form a theory, test minimally.
4. Backward root-cause-tracing — trace the symptom backward level-by-level through the call stack to the origin where invalid data/state was introduced; the fix-point is the source, not the symptom. Pass the intake fields (and the plan reports dir, if running inside one) to the subagent.

If intake (§1) surfaces ≥2 independent hypotheses (e.g. two unrelated suspect components), spawn one debugger instance per hypothesis in parallel (≤4, read-only — no ownership conflict possible; see workflows/parallel-execution.md §4). Single clear hypothesis → one instance, unchanged.

3. Verify

The debugger's report is an UNVERIFIED claim (Verification Gate, development-rules.md). Confirm the root cause is backed by concrete evidence — log excerpts, stack/trace, code refs (file:line), or a reproduction — not speculation. Reject symptom-level conclusions.

4. Report

Return a concise root-cause report:

• Root cause — 1-2 lines: the origin defect.
• Evidence chain — symptom → trace-back steps → origin (with file:line, logs).
• Confidence — high / medium / low. If not definitive, list ranked likely causes + next investigation steps.
• Suggested remediation direction — where & how to fix conceptually (NO code). May suggest /vk-plan or /vk-fix as the next step. Save as an inter-agent report in plans/<plan-name>/reports/ only when running inside a plan dir; otherwise present inline.

IMPORTANT: Do NOT implement the fix automatically. IMPORTANT: No root-cause claim without fresh, concrete evidence. IMPORTANT: Activate the debugging skill; /vk-scout to locate files.