# Ix Understand

> Build a mental model of a system, subsystem, or the whole repo. Graph-first, no code reads unless necessary.

- Skill: `ix-infrastructure/ix-understand` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ix-infrastructure/ix-understand`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ix-infrastructure/ix-understand/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML, Coding & Dev Tools
- Author: ix-infrastructure (https://skillmd.com/u/ix-infrastructure)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ix-infrastructure/ix-understand

---


Check `command -v ix` first. If unavailable, 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
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:
```bash
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.

## 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
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
ix explain <component> --format llm
```

Hard limits: No `ix read`. No `ix map`. No `ix trace`. This skill never reads source code.

## Output

```text
# [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.