# 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-3` (Agent Skill)
- Install (CLI): `npx get-skill add ix-infrastructure/ix-understand-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ix-infrastructure/ix-understand-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ix-infrastructure (https://skillmd.com/u/ix-infrastructure)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ix-infrastructure/ix-understand-3

---


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.

