ix-understand

name	ix-understand
description	Build a mental model of a system, subsystem, or the whole repo. Graph-first, no code reads unless necessary.
metadata	{"openclaw":{"requires":{"bins":["ix"]}}}

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:

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:

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:

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:

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.