Menu
Build a mental model of a system, subsystem, or the whole repo. Graph-first, no code reads unless necessary.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Analyze system design — structure, coupling, code smells, and high-risk hotspots. Purely graph-based, no code reads.
Root cause analysis — trace execution path to a failure, narrow candidates, read minimal source only at suspected failure points.
Generate narrative-first, importance-weighted documentation for a repo, system, or subsystem with a selective reference layer. Use --full for deeper module/class/method coverage.
Route to the right Ix skill or command for your task
Change risk analysis — blast radius, affected systems, and what to test. Depth scales with risk level; low-risk targets stop early.
Deep dive into a symbol, feature, or bug. Graph-first, minimal code reads, early stopping when sufficient evidence found.
| name | ix-understand |
| description | Build a mental model of a system, subsystem, or the whole repo. Graph-first, no code reads unless necessary. |
| argument-hint | ["target — subsystem name","path","or empty for whole repo"] |
Check command -v ix first. If unavailable, stop and say so.
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?
Run in parallel:
ix subsystems --format llm
ix rank --by dependents --kind class --top 10 --exclude-path test --format llm
ix rank --by callers --kind function --top 10 --exclude-path test --format llm
If $ARGUMENTS is a named symbol or subsystem (not empty, not ., and not a filesystem path), also run:
ix locate "$ARGUMENTS" --format llm
Note: ix locate resolves symbol names only — skip it entirely when the target is . or an empty string (whole-repo); the subsystem + rank results above are sufficient.
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.
Pick the 2-4 most central or unclear components from Phase 1 results. Run in parallel:
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.
For at most 2 components still unclear after Phase 2:
ix explain <component> --format llm
Hard limits: No ix read. No ix map. No ix trace. This skill never reads source code.
# [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.
Count and parity claim rule: Any specific number in the output — tool count, method count, file count, caller count, version string, or a parity claim about another system — must have been returned by an ix command run in this session. If the number was not directly surfaced by a command in this run, write unknown instead. Training-data recall does not qualify for the [graph] label; [graph] means a command in this session returned the value.
Scope fence: Claims in the output describe the target of this run only. Do not make claims about sister repos, related plugins, or other systems unless this run explicitly queried them with an ix command. If a comparison to another system is needed, mark it [unverified] and recommend ix-understand <other-target> to confirm.