ix v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/4541f51dfa92bbed.

---
name: ix
description: "This skill should be used when answering structural questions about a codebase: understanding what a symbol is, tracing flows, measuring change impact, finding callers/callees/imports, or detecting code smells. It drives the Ix CLI (ix map/explain/trace/impact/search/rank/smells) against a persistent code graph stored in a local backend, instead of grepping or guessing. Run scripts/bootstrap.sh once to install the CLI and start the backend, then ix map on the repo root."
license: Apache-2.0
metadata:
  version: 1.0.0
  source: https://github.com/ix-infrastructure/Ix
---

# Ix — Persistent Codebase Map

## Overview

Ix parses a repository with tree-sitter (26 languages), builds a graph of its symbols, calls, and imports, and stores it in a local backend (ArangoDB via Docker). Query that graph with `ix` commands to answer bounded, structural questions instead of reading files blindly. The graph persists between sessions.

Use this skill whenever the question is about structure, relationships, or impact: what a symbol is, what calls it, what it calls, how data flows, what breaks if a change lands, which files are most depended-on, or where the smells are.

## When to Use

- Answering "what is this / what does it touch" questions about a symbol, class, or module.
- Tracing how a flow moves through the system.
- Estimating blast radius before a change.
- Finding callers, callees, imports, and dependents.
- Detecting smells, ranking hotspots, and scoring subsystems.
- Onboarding to an unfamiliar codebase.

Do not use this skill for prose-style or history questions — use it for structural, graph-backed answers.

## Quick Start (first run)

Map the target repo with the bootstrap script:

```bash
bash scripts/bootstrap.sh [repo-root] [--no-map]                                            # Bash / Git Bash / macOS / Linux
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 [repo-root] [-NoMap]         # Windows PowerShell
```

The bootstrap checks Node >= 22, git, Docker, and ripgrep; installs the `ix` CLI if missing; starts the local Docker backend; and maps the repo by default. Re-run `scripts/bootstrap.sh` on each new repo to register and map it.

Refresh the graph after code changes:

```bash
ix map --silent
```

## Core Workflow

Map → Explain → Trace → Impact

| Step | Command | Example |
|---|---|---|
| Build/refresh the graph | `ix map` | `ix map .` |
| Understand a component | `ix explain` | `ix explain IngestionService` |
| Bounded deterministic context | `ix context` | `ix context IngestionService --max-entities 20` |
| Trace a flow | `ix trace` | `ix trace user_login_flow` |
| Analyze impact | `ix impact` | `ix impact verify_token --format llm` |

## Using the Skill

1. Start with high-level commands for one-shot answers: `ix overview`, `ix impact`, `ix rank`.
2. Drill down with primitives — `ix search`, `ix callers`, `ix callees`, `ix contains`, `ix imports`, `ix imported-by`, `ix depends` — reusing exact entity IDs from prior JSON output.
3. Prefer `--format llm` when reading output yourself (token-minimal); use `--format json` when chaining commands or extracting a field. See references/output-formats.md.
4. For the full command surface, decomposition recipes, and best practices, load references/commands.md; for a command's complete flag list, load references/flags.md.
5. If the backend is unreachable or a command fails, load references/troubleshooting.md.

## Rules

1. Before answering codebase questions, run targeted `ix` commands. Do not answer from training data alone.
2. After noticing contradictory information, run `ix conflicts` and present the results.
3. Never guess codebase facts — if Ix has structured data, use it.
4. Immediately after modifying code, run `ix map --silent` to re-ingest.
5. When Ix reports low confidence, mention the uncertainty to the user, suggest re-running `ix map`, and never present low-confidence data as established fact.

## References

- **references/commands.md** — full command routing tables, decomposition recipes, best practices, and the do-not-use list. Load before running any command beyond the core four above.
- **references/flags.md** — every flag the CLI registers, per command, with values and defaults. Load when a command needs shaping beyond the examples in commands.md, or to check whether a flag exists before guessing.
- **references/output-formats.md** — `--format llm|json|text` rules, commands that do not implement `llm`, and Pro-gated commands. Load when formatting output or when a "requires Ix Pro" error appears.
- **references/troubleshooting.md** — prerequisites, backend health checks, `ix doctor`, and environment flags. Load when a command fails or the backend is unreachable.

## Scripts

- **scripts/bootstrap.sh** — cross-platform first-run setup (bash; works on macOS, Linux, and Windows under Git Bash / MSYS2 / WSL).
- **scripts/bootstrap.ps1** — native Windows PowerShell first-run setup.