# Ix Debug

> Root cause analysis — trace execution path to a failure, narrow candidates, read minimal source only at suspected failure points.

- Skill: `ix-infrastructure/ix-debug-2` (Agent Skill)
- Install (CLI): `npx get-skill add ix-infrastructure/ix-debug-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ix-infrastructure/ix-debug-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ix-infrastructure (https://skillmd.com/u/ix-infrastructure)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ix-infrastructure/ix-debug-2

---


## 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.

