ix-debug

## Argument parsing Strip `--save` and any following path token from `$ARGUMENTS` before resolving the entry point. - If `--save <path>` is present, set `SAVE_PATH` to that path. - If `--save` is present without a path, auto-generate `ix-debug-<target-slug>.md` in cwd (target slug = the first symbol or first three words of the symptom with spaces and slashes replaced by `-`). - If `--save` is absent, `SAVE_PATH` is empty — do not write a file. ## Pro check (optional) Call `ix_briefing` with `{}`. If `ok` is `true`, Pro is available. Extract `data.decisions` for use in Pro steps below. If it returns `ok: false`, skip all **[Pro]** labeled steps. **[Pro]** If `data.decisions` is non-empty, scan for a recorded decision matching this symptom area before proceeding. Surface any relevant match — it may already explain the behavior or constrain the fix. ## Goal Answer: *where in the execution path is this likely failing, and why?* Stop once you have 1–3 root cause candidates with supporting evidence. ## Phase 1 — Locate the entry point (always) Call `ix_locate` with `{ "symbol": "<$ARGUMENTS>" }`. If `$ARGUMENTS` is a symptom description rather than a symbol name, also call `ix_text` with `{ "pattern": "<$ARGUMENTS>", "limit": 10 }`. Identify the most likely entry point (where the failure originates or first manifests). ## Phase 2 — Explain (always) Call `ix_explain` with `{ "symbol": "<entry-point>" }`. Extract: `role.role`, `importance.level`, `facts.callerCount`, `facts.calleeCount`. Identify whether this is: - A **boundary** (external input, API, event) — failure likely from unexpected input - An **orchestrator** — failure likely from wrong sequencing or state - A **utility/helper** — failure likely from wrong assumptions by caller **Stop if:** the explanation makes the failure source obvious → skip to Output. ## Phase 3 — Decide: inline or delegate Use the Phase 1–2 results to choose the path: - **Inline path (simple bug):** the likely failure is still within a single subsystem, the role confidence is high, and `facts.calleeCount` ≤ 10 → continue to Phase 4. - **Delegate path (complex bug):** role confidence is low, OR `facts.calleeCount` > 10 → use the Agent tool with `subagent_type: "ix-memory:ix-bug-investigator"` and pass the pre-computed context below. **You MUST pass pre-computed context so the agent skips redundant work.** Launch the agent with: > Investigate: $ARGUMENTS > > **Pre-computed context (skip Steps 1–2):** > Entry point: [symbol, subsystem, file — from Phase 1] > Entity type: [boundary / orchestrator / utility — from Phase 2] > Explain output: [paste ix_explain result] > > Start from Step 3. The symptom is: [description]. The entry point classification suggests: [hint from Phase 2]. If the Agent tool is unavailable, continue inline through Phases 4–6, reduce breadth, preserve the 2-read cap, and surface uncertainty rather than over-reading. ## Phase 4 — Trace the execution path (inline path) Call `ix_trace` with `{ "symbol": "<entry-point>" }`. Walk the downstream path. At each step, look for: - Functions that validate or transform state (potential incorrect assumptions) - Cross-subsystem calls (where contracts might differ) - Functions with high callee count (potential god functions, many failure points) **Narrow:** Identify the 1–3 nodes most likely to contain the bug. **Delegate if:** the trace crosses subsystem boundaries, reveals multiple plausible contract boundaries, or fans out enough that confidence drops. Use the Phase 3 delegation prompt. **Stop if:** trace reveals an obvious candidate → proceed to Phase 6. ## Phase 5 — Callers (inline path, if failure might come from upstream) Call `ix_callers` with `{ "symbol": "<entry-point>" }` (limit 10). Check whether the fault is in how this is *called* rather than in its own logic. ## Phase 6 — Targeted code read (inline path, only at suspected failure points) For each root cause candidate (max 2): Call `ix_read` with `{ "symbol": "<candidate-function>" }`. Read **the specific function only**. Look for: - Edge cases in input handling - Assumptions about state that might be violated - Missing null/error checks - Incorrect sequencing **Hard limit:** 2 `ix_read` calls maximum. If still ambiguous, surface the candidates and uncertainty to the user. ## Phase 7 — Synthesize - If you delegated in Phase 3 or 4, present the agent's result directly. Do not re-run locate/explain/trace in the main thread. - If you stayed inline, use the Output format below. ## Output ``` ## Debug: [entry point] **Execution path:** [entry-point] → [step] → [step] → [suspected failure point] **Root cause candidates:** 1. [function/file] — [reason: what assumption might be wrong] 2. [function/file] — [reason] **Evidence:** - [what graph data supports each candidate] - [what code read revealed, if any] **Confidence:** [high / medium / low] — [why] **Next steps:** - Add logging at [specific point] to confirm - Check [specific edge case] in [function] - Run `/ix-investigate <X>` to understand [unclear component] more deeply ``` ## Save step **Only if `SAVE_PATH` is non-empty:** - Write the full output to `SAVE_PATH`. - Confirm to the user: `Saved to <SAVE_PATH>`. - Do not write the file if `--save` was not passed.