ix-understand

Run `command -v ix` to verify ix is on PATH. Never use tilde paths (`~/...`) or absolute paths — always invoke `ix` directly via PATH. If not found, stop and say so. ## Goal Build an accurate mental model of the target's structure, purpose, and key components. Stop as soon as you can answer: *what does this do, what are its key parts, and where should someone explore next?* ## Phase 1 — Orient (always run) Run in parallel: ```bash timeout 60s ix subsystems --format llm timeout 60s ix rank --by dependents --kind class --top 10 --exclude-path test --format llm timeout 60s ix rank --by callers --kind function --top 10 --exclude-path test --format llm ``` If `$ARGUMENTS` is non-empty, also run: ```bash timeout 60s ix locate "$ARGUMENTS" --limit 5 --format llm ``` Extract from subsystems: region names, file counts, cohesion scores. Extract from rank: the 3–5 most structurally central classes and functions. **Stop here if:** `$ARGUMENTS` is empty and rank + subsystems give a clear picture. ## Phase 2 — Key components (run only if needed) Pick the **2–4 most central or unclear** components from Phase 1 results. Run in parallel: ```bash timeout 60s ix overview <component> --format llm ``` Do NOT run `ix explain` yet. `ix overview` is cheaper and sufficient for most components. **Stop here if:** you can describe what each component does and how they relate. ## Phase 3 — Clarify (run only if still unclear) For at most **2** components still unclear after Phase 2: ```bash timeout 60s ix explain <component> --format llm ``` **Hard limits:** No `ix read`. No `ix map`. No `ix trace`. This skill never reads source code. ## Output ``` # [Target] — System Overview ## What it does [One paragraph. Purpose, primary job, who uses it.] ## Key Components - **X** (<kind>) — [role in one line, evidence: rank position / cohesion score] - **Y** (<kind>) — [role in one line] [3–5 max. Omit if fully explained by parent.] ## Structure [Subsystem breakdown: name → file count → cohesion score → what it owns] ## Where to explore next - `/ix-investigate <X>` — understand the most central component - `/ix-architecture` — analyze coupling and design health - `/ix-debug <X>` — if investigating a suspected bug ``` **Evidence labels:** Mark every claim as `[graph]` (direct ix data) or `[inferred]` (structural reasoning). Never state facts without one of these labels.