ix-infrastructure/ix-gemini-plugin/ix-understand

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?

If Ix is unavailable (tool calls fail, or ix_health() reports the backend unreachable), proceed with best-effort analysis.

Preferred path — one call

If $ARGUMENTS names a target, call ix_context first and use its ranked evidence (definition, members, callers, importers, related files) as the backbone of the answer:

ix_context({ target: $ARGUMENTS })

For a whole-repo question (no target), start at Phase 1. Supplement with the phases below if the evidence needs more detail.

Phase 1 — Orient (always run)

Call in parallel:

• ix_subsystems() — architectural regions, file counts, cohesion
• ix_rank({ by: "dependents", kind: "class", top: 10 }) — most central classes
• ix_rank({ by: "callers", kind: "function", top: 10 }) — most called functions

If $ARGUMENTS is non-empty, also call:

• ix_locate({ symbol: $ARGUMENTS }) — resolve the target in the graph

Extract: region names, file counts, cohesion scores; top 3-5 structurally central components.

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. Call in parallel:

• ix_overview({ target: <component> }) for each

Do NOT call 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:

• ix_explain({ symbol: <component> })

Hard limits: No source code reads. 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 tool data) or [inferred] (structural reasoning). Never state facts without one of these labels.