ix-understand

name	ix-understand
description	Build a detailed architectural mental model of a system, subsystem, or the whole repo. Graph-first, source reads only when needed for data flow or key patterns.

Flag parsing

Parse $ARGUMENTS before doing anything else:

• The first non-flag token is TARGET (may be empty — means whole repo)
• --shallow: orient only, no agents (default if no flag given)
• --medium: single agent regardless of system count
• --deep: full parallel agent strategy
• --save [path]: if present, set SAVE_PATH; path is optional — if absent, auto-generate ix-understand-<target-slug>.md in cwd (target slug = TARGET with spaces and slashes replaced by -, or repo if TARGET is empty); if --save is not given at all, SAVE_PATH is empty.

MANDATORY for --medium and --deep: This skill MUST use the Agent tool (subagent_type: "ix-memory:ix-system-explorer") for all exploration work. Do NOT call ix tools yourself except for the Phase 1 orient calls below. All subsystem exploration MUST be delegated to agents.

Phase 1 — Orient

Call these tools in parallel to discover the architecture:

• ix_subsystems with {}
• ix_rank with { "by": "dependents", "kind": "class", "top": 15 }
• ix_rank with { "by": "callers", "kind": "function", "top": 15 }
• ix_stats with {}

From the results, identify:

• All top-level systems (names, file counts, cohesion, coupling scores)
• The top 10–15 structurally important classes and functions
• Total codebase scale (files, nodes, edges)

If TARGET is set, scope the orient to that target's subsystems.

Confidence check: Scan confidence scores in the ix_subsystems results:

• Any system with confidence < 0.5: add this caveat to the final output header: ⚠ Graph boundary confidence is low for [system] (${confidence}). Structural claims for this region may not reflect actual file relationships.
• Any system with confidence < 0.3: report fuzzy boundary as an explicit finding. Label all structural claims for that region as [uncertain].

Depth routing

Choose the path based on the parsed depth flag:

--shallow (default)

Synthesize from Phase 1 data only — no agents. Produce:

# [TARGET or "Whole Repo"] — System Overview

**Scale:** [files, nodes, edges — from ix_stats]

## Subsystem Map
| Subsystem | Files | Cohesion | Coupling | Role |
|-----------|-------|----------|----------|------|
[one row per subsystem from ix_subsystems]

## Top Classes (by dependents)
[top 10 from ix_rank results]

## Top Functions (by callers)
[top 10 from ix_rank results]

## Quick Assessment
[1–2 sentences on overall shape and structural health based on the metrics]

Then stop. Suggest deeper options at the bottom:

For a single-agent summary: /ix-understand [target] --medium For full parallel analysis: /ix-understand [target] --deep

--medium

Launch a single ix-memory:ix-system-explorer agent regardless of system count. Do not proceed to Phase 2.

Pass:

Build an architectural mental model of: $TARGET (or the whole repo if no target)

Orient data (pre-computed): [Paste Phase 1 results — subsystem list, top components, stats]

Skip Step 1 — orient data is provided. Start from Step 2.

Depth: Cover all major subsystems at one level of depth each. Prioritize breadth over depth — no need to drill into internals of every component.

Label every claim as [graph] or [inferred].

Present the agent's output directly to the user. Do not proceed to Phase 2.

--deep

Continue to Phase 2.

Phase 2 — Decide: serial or parallel (--deep only)

Count the number of significant top-level systems (file count >= 10 or confidence >= 0.5).

• ≤ 3 significant systems: Launch a single ix-system-explorer agent with the full prompt (Phase 3A).
• > 3 significant systems: Launch parallel ix-system-explorer agents, one per system (Phase 3B).

Phase 3A — Single agent (--deep, small codebase)

You MUST use the Agent tool with subagent_type: "ix-memory:ix-system-explorer" here. Do NOT do this work yourself. Launch one agent with:

Build a detailed architectural mental model of: $TARGET

If no target is specified, explore the whole repo.

Orient data (pre-computed): [Paste the orient results from Phase 1 — subsystem list, top components, stats]

Skip Step 1 — orient data is provided above. Start from Step 2.

Depth expectations: Comprehensive architectural document for onboarding. Go wide AND deep. Enumerate all major subsystems. For important ones, drill into internal structure.

What to cover: subsystem internals, type system, data flows (ASCII diagrams), key components (up to 15), build/test infra, coupling, risks (security/complexity/data integrity), navigation shortcuts, where to go deeper.

Label every claim as [graph] or [inferred]. Use tables and ASCII diagrams.

Then present the agent's output directly to the user.

Phase 3B — Parallel agents (--deep, large codebase)

You MUST use the Agent tool with subagent_type: "ix-memory:ix-system-explorer" for each system. Launch ALL agents in a single message (this runs them in parallel). You must wait for all agents to return before proceeding to Phase 4. Each agent gets:

Explore the $SYSTEM_NAME subsystem in detail.

Orient data (pre-computed): [Paste the full orient results so each agent has global context]

Skip Step 1 — orient data is provided. Start from Step 2 scoped to $SYSTEM_NAME.

What to produce:

1. What $SYSTEM_NAME does — purpose, path, file count, role in the architecture
2. Internal structure — sub-components table (name, path, kind, role)
3. Key types and abstractions within this system
4. Top 3–5 most important components (with ix_explain) — role, dependents, callers
5. Primary data flow within this system (ASCII diagram if applicable)
6. External coupling — which OTHER systems does this one connect to and how?
7. Risk areas specific to this system
8. 1–2 ix_read calls only if the graph left key patterns unclear

Output format:

## $SYSTEM_NAME (path)

**Purpose:** [one sentence]
**Scale:** [file count, key entity counts]

### Internal Structure
| Component | Kind | Role |
|-----------|------|------|

### Key Components
| Component | Location | Role | Dependents | Risk |
|-----------|----------|------|------------|------|

### Data Flow
[ASCII diagram if applicable]

### External Coupling
[Which systems it connects to, edge counts, coupling direction]

### Risks
[Specific risks with file paths]

Label every claim as [graph] or [inferred].

Include one additional ix-system-explorer agent in the same single message for cross-cutting concerns:

Analyze cross-system structure for this codebase.

Orient data (pre-computed): [Paste orient results]

Using the graph tools, determine:

1. Core type system / data model — what are the fundamental types shared across systems? Call ix_rank with { "by": "dependents", "kind": "class", "top": 15 } and ix_explain on the top 5.
2. Primary data flows — trace 1–3 key execution paths end-to-end across system boundaries using ix_trace. Produce ASCII diagrams.
3. Build & development infrastructure — call ix_inventory with { "kind": "file", "path": "test" } and ix_inventory with { "kind": "file", "path": "cmd" }.
4. Cross-system coupling hotspots — which system pairs have the most edges between them?
5. Navigation shortcuts — "To find X, look at Y" table for common tasks.
6. Where to go deeper — specific ix tools for follow-up.

Label every claim as [graph] or [inferred].

Phase 4 — Synthesize (--deep only)

Do NOT proceed until ALL agents from Phase 3 have returned. Once all agents complete, you (not an agent) assemble the final document:

# System: [name or "Whole Repo"]

## Overview
[What the system is and does — purpose, language, scale. Sourced from orient data.]

## Architecture

### System Map
[Table of ALL top-level systems with file counts, cohesion, coupling, roles — from orient data]

[Insert each subsystem agent's output as its own ### section]

## Core Abstractions / Type System
[From cross-cutting agent]

## Data Flows
[From cross-cutting agent — ASCII diagrams showing end-to-end paths across systems]

## Key Components
[Merged table from all subsystem agents, sorted by dependents descending, top 15]

| Component | System | Location | Role | Dependents | Risk |
|-----------|--------|----------|------|------------|------|

## Build & Development Infrastructure
[From cross-cutting agent]

## Dependencies & Coupling
[From cross-cutting agent — cross-system coupling hotspots + external deps]

## Risk Areas

### Security Risks
[Merged from all agents]

### Complexity Risks
[Merged from all agents]

### Data Integrity Risks
[Merged from all agents]

## Navigation Shortcuts
[From cross-cutting agent]

| To find... | Look at... |
|------------|-----------|

## Where to Go Deeper
[From cross-cutting agent]

## Selective Reference
[Top 15–20 most important entities across all systems — merged and deduplicated]

Quality bar: The final document must be comprehensive (all systems covered), specific (file paths, counts), structured (tables, ASCII diagrams), actionable (navigation shortcuts), and evidenced ([graph] or [inferred] labels).

Save step

Only if SAVE_PATH is non-empty (i.e., --save was passed):

• Write the full output above to SAVE_PATH.
• Confirm to the user: Saved to <SAVE_PATH>.
• Do not write the file if --save was not passed.