# Ix Docs

> Generate narrative-first, importance-weighted documentation for a repo, system, or subsystem with a selective reference layer. Use --full for deeper module/class/method coverage.

- Skill: `ix-infrastructure/ix-docs-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ix-infrastructure/ix-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ix-infrastructure/ix-docs-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ix-infrastructure (https://skillmd.com/u/ix-infrastructure)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ix-infrastructure/ix-docs-2

---


## Goal

Produce documentation that helps a new engineer understand the system quickly and gives an LLM strong architectural context without drowning it in low-value detail.

Write like real engineering documentation for a framework or subsystem:
- teach the system
- explain how it works
- show where the important parts live
- surface risks and fragile boundaries
- point the reader to the next files or symbols to inspect

Never write a raw report dump.

---

## Core model

Every `ix-docs` run produces **two layers**:

1. **Narrative layer** (always first) — human-readable explanation, onboarding-focused, architecture, flow, usage, risks, navigation guidance
2. **Reference layer** (always present, but selective) — compressed summaries of important modules, classes, and services; short, structured, high-signal entries; no code dumping

**Mode behavior**
- `ix-docs <target>`: narrative-heavy by default, with a minimal selective reference appendix
- `ix-docs <target> --full`: deeper coverage for important components, still importance-weighted

**Style behavior**
- `--style narrative` (default): prose-first narrative sections; reference layer stays compact
- `--style reference`: tighter, docs-site style structure; narrative stays brief but is not removed
- `--style hybrid`: full narrative plus fuller selective reference; best match for `--full`

---

## Flags

| Fragment | Variable | Default |
|---|---|---|
| first non-flag token | `TARGET` | required |
| `--full` | `FULL=true` | false |
| `--style narrative\|reference\|hybrid` | `STYLE` | `narrative` |
| `--split` | `SPLIT=true` | false |
| `--single-doc` | `SINGLE=true` | false |
| `--out <path>` | `OUT_PATH` | auto-detect |
| `--save [path]` | alias for `--out` when `--out` is absent; if both are given, `--out` wins | — |

**Parsing**
Scan `$ARGUMENTS` left to right:
- The first token that does not begin with `--` is `TARGET`
- `--style` and `--out` consume the next token as their value (also accept `--style=value` form)
- All other flags are boolean toggles
- If `TARGET` is missing, stop and ask the user to supply a target before continuing

**Output rules**
- `--single-doc` forces one Markdown file
- `--split` produces a directory with `index.md` plus per-system or per-subsystem docs
- if neither is set and `FULL=true` on a repo with more than 10 subsystems, auto-enable `SPLIT=true`
- `--single-doc` overrides auto-splitting

**Output path auto-detection**
1. `docs/` exists at workspace root → `docs/<target-name>.md` or `docs/<target-name>/`
2. `doc/` exists → `doc/<target-name>.md` or `doc/<target-name>/`
3. otherwise → `<target-name>.md` or `<target-name>/` at workspace root

If `FULL=true`, tell the user the planned mode, output path, and whether splitting was auto-enabled before generating the docs.

---

## Non-negotiable rules

1. **Graph first** — start with `ix_subsystems`, `ix_overview`, `ix_rank`, `ix_explain`; use `ix_read` only after graph data leaves an important behavior unclear
2. **Importance-weighted expansion** — expand detail by centrality, risk, coupling, orchestration role, and user focus; never treat all modules equally
3. **Selective low-level detail** — default mode: module and class summaries only for important parts; full mode: method summaries only for key classes or services
4. **No raw dumps** — never output raw JSON, never paste tool logs, never dump full inventories
5. **No redundancy** — group repeated patterns; if several modules have the same role, summarize the pattern once
6. **Code reads are rare** — default mode: at most 2 `ix_read` calls total; full mode: at most 5 `ix_read` calls total; symbol-level only

---

## Coverage policy

Use the following ranking factors to decide what gets expanded:
1. **Centrality**: `ix_rank` results, caller count, dependent count
2. **Risk**: `ix_impact`
3. **Coupling**: cross-system or cross-subsystem relationships
4. **Orchestration role**: coordinators, entry points, workflow managers from `ix_explain`
5. **User focus**: the exact target and its immediate neighborhood

### Always include
- top-level architecture
- all major subsystems in scope
- the most important modules or services

### Sometimes include
- important files
- key classes or services
- notable boundary functions or entry points

### Only in `--full`
- selective method summaries for the most important classes or services
- expanded per-subsystem module coverage

### Never
- exhaustive inventories
- equal treatment for every module
- long method lists

### Expansion budgets

**Default mode**
- repo or large system: cover all major subsystems, expand the top 3–5 most important ones, reference 5–8 key components total
- subsystem or module: expand the target fully, reference the top 5–8 entities in scope

**Full mode**
- repo or large system: cover all major systems, expand the top 5–8 by importance
- subsystem or module: expand the top 8–12 entities, add method summaries for the top 3–5 classes or services only

---

## Command strategy

Do not call every tool mechanically. Reuse earlier results and stop when additional depth would not materially improve the documentation.

### Phase 1 — Scope

**Stop early:** If `TARGET` is an unambiguous symbol or small component and scope is clear from `ix_stats` alone, skip the remaining Phase 1 calls and proceed to Phase 2.

Always start by calling in parallel:
- `ix_stats` with `{}`
- `ix_subsystems` with `{}`
- `ix_briefing` with `{}`

**Pro check:** If `ix_briefing` returns `ok: true`, Pro is available. Extract `data.goals`, `data.decisions` for use in **[Pro]** steps. If it returns `ok: false`, skip all Pro-labeled steps.

If `TARGET` is not obviously the whole repo, call `ix_locate` with `{ "symbol": "<TARGET>" }`.

Resolve whether the target is: repo / top-level system / subsystem / module or file / class, service, or symbol. If ambiguous, resolve before proceeding.

### Parallel agent dispatch (large / full-mode runs)

**Trigger:** `FULL=true` AND the target is a repo or top-level system with **more than 5 subsystems**.

**Phase 1 reuse:** If subsystem and rank data is already present in context from a prior `/ix-understand` run in this session, skip those Phase 1 calls and use the cached data directly.

**Step 1 — Per-system agents:** From the Phase 1 rank results, select the top systems by importance (cap at 5). For each, spawn one `ix-system-explorer` agent:

> Task template: *"Build a complete architectural mental model of `$SYSTEM` within `$TARGET`. Focus on: (1) internal module structure and responsibilities, (2) the most important and most-coupled components, (3) main execution flows within this subsystem, (4) outbound dependencies and shared interfaces with other subsystems. Return structured findings with: a one-paragraph subsystem summary, top 5 important modules with roles, key internal flows, and coupling risks."*

**Step 2 — Cross-cutting agent:** Immediately after spawning the per-system agents, spawn one additional `ix-system-explorer` agent:

> Task: *"In the `$TARGET` codebase, identify only what crosses subsystem boundaries: (1) shared types, base classes, and utilities used across multiple subsystems, (2) cross-system execution flows and handoff points, (3) infrastructure or platform services that multiple systems depend on, (4) god-modules or highly-central components visible from the dependency graph. Do NOT explore individual subsystems in depth — focus exclusively on cross-cutting structure. Return structured findings."*

**Do not wait** for agents before starting Phase 2. Continue running Phase 2 calls while agents work.

**Step 3 — Synthesis:** Merge agent findings with Phase 2/3 graph results. Per-system outputs → per-system narrative sections. Cross-cutting output → Dependencies & Relationships section. If an agent contradicts graph data, prefer the graph. If an agent fails, continue without it and note the gap.

**Skip this dispatch entirely** if: `FULL=false`; target is a subsystem, module, or symbol; or the repo has 5 or fewer subsystems.

### Phase 2 — Architecture

**Stop when:** you have identified the top 3–5 important components and the subsystem structure is clear.

Call in parallel (as relevant):
- `ix_overview` with `{ "target": "<TARGET>" }` (skip if TARGET is the whole repo)
- `ix_rank` with `{ "by": "dependents", "kind": "class", "top": 10 }`
- `ix_rank` with `{ "by": "callers", "kind": "function", "top": 10 }`

For module or file targets, also call:
- `ix_imports` with `{ "symbol": "<TARGET>" }`

Full mode: raise rank `top` to 20; inspect the most important systems first, never alphabetically.

### Phase 3 — Behavior

**Stop when:** the main execution flow is understood. Skip `ix_trace` if `ix_explain` results are sufficient.

Call `ix_explain` with `{ "symbol": "<TARGET>" }`.

Also call `ix_explain` for the most important orchestrators, services, or entry points identified in Phase 2.

Behavior budget:
- default mode: explain the top 3–5 important entities
- full mode: for each important subsystem, explain the top 5 classes or services and the top 3 functions or entry points

Optional: call `ix_trace` with `{ "symbol": "<entry-point>" }` only if the main execution flow is still unclear after `ix_explain`. Do not narrate every edge in a trace.

### Phase 4 — Relationships

**Stop when:** for symbol-level or small single-module targets, skip this phase entirely.

**Repo-level guard:** If TARGET is the whole repo, skip `ix_callers`, `ix_callees`, and `ix_depends` on the repo itself — these are not meaningful at repo scope. Instead run them for the top 3–5 boundary components identified in Phase 2.

Call as relevant:
- `ix_callers` with `{ "symbol": "<TARGET>" }` (limit 15)
- `ix_callees` with `{ "symbol": "<TARGET>" }` (limit 15)
- `ix_depends` with `{ "symbol": "<TARGET>", "depth": 2 }`

For large result sets: group callers by subsystem, summarize repeated patterns, never list more than 15 similar names individually.

### Phase 5 — Risk

**Repo-level gate:** If TARGET is the whole repo, skip `ix_impact` on the repo itself. Instead run it for the top 3–5 high-centrality entities from Phase 2.

Otherwise call `ix_impact` with `{ "target": "<TARGET>" }`.

Full mode: also run `ix_impact` for the top 2–5 high-centrality entities.

### Phase 6 — Health

**Stop when:** for symbol-level or single-module targets, skip this phase.

Call `ix_smells` with `{}`. Filter by path prefix after retrieval if the target is a subsystem or module.

**[Pro]** If Pro is available and `data.decisions` is non-empty, incorporate relevant architectural decisions in the risk and complexity section.

Prioritize: god modules, highly coupled regions, orphaned components, subsystems with weak boundaries. Group health issues by subsystem, not as a flat dump.

### Phase 7 — Optional reads

**Stop when:** you reach the read budget. Never exceed it — omit or note gaps instead.

Only read code when graph data is insufficient for an important behavior.

Allowed use cases:
- orchestrators with unclear control flow
- critical entry points on the main execution path
- high-risk components whose role is still ambiguous after `ix_explain`

Call `ix_read` with `{ "symbol": "<symbol>" }`. Extract only the behavior needed to clarify the docs — do not summarize implementation line-by-line.

---

## Writing rules by style

### `--style narrative`
- lead with prose; each narrative section should explain how to think about the system
- reference layer stays compressed

### `--style reference`
- keep the narrative layer first, but tighten it to short paragraphs
- use more headings, bullets, and compact summaries
- reference layer more prominent than in narrative mode

### `--style hybrid`
- full narrative layer plus fuller reference layer
- best option for `--full`, onboarding docs, and handoff docs

---

## Output structure

```markdown
# [Target] — Documentation

> Generated: [date]
> Scope: [repo | system | subsystem | module | symbol]
> Mode: [standard | full]
> Style: [narrative | reference | hybrid]
> Evidence quality: [strong | partial | weak]
> Coverage: [what was expanded vs summarized]

## Part 1 — Narrative

### 1. Overview
- what the system is, what it does, why it exists
- **[Pro]** active project goals this system serves (from briefing data.goals), if available

### 2. Architecture
- systems → subsystems → modules
- boundaries and responsibilities
- high-level structure

### 3. How It Works
- main execution flows
- request or data lifecycle
- orchestration paths

### 4. Key Components
- the most important modules, classes, or services
- why they matter

### 5. Dependencies & Relationships
- major dependencies
- cross-system interactions
- important coupling points

### 6. Risk & Complexity
- high-risk areas
- fragile components
- change sensitivity

### 7. How to Work With This Repo
- where to start
- how to navigate
- common workflows
- what to modify carefully

### 8. Where to Go Deeper
- next files, modules, or symbols to inspect
- suggested exploration paths

## Part 2 — Selective Reference

### Module Summary
For each major module: purpose, responsibilities, dependencies, key contained components

### Class / Service Summary
For each important class or service: role, what it manages, where it is used

### Method Summary
Only in `--full`, and only for key classes or services: method name, 1–2 line role summary
```

---

## Split output

Use split output when `--split` is passed or `FULL=true` on a large repo.

```
<OUT_DIR>/
  index.md
  <system-1>.md
  <system-2>.md
  ...
  <lower-ranked-system>-stub.md
```

`index.md` should contain: overall overview, top-level architecture, most important cross-system flows, navigation guidance, links to per-system docs.

Per-system docs: full narrative structure plus selective reference for that system.

Stubs for lower-ranked systems: one-paragraph overview, top 3 components, one risk note, instruction to rerun `/ix-docs <system> --full` for deeper coverage.

---

## Post-write confirmation

After writing the file or files, confirm:

```
Documentation written.

Mode:   [standard | full]
Style:  [narrative | reference | hybrid]
Output: [path or directory]
Scope:  [repo/system/subsystem/module/symbol]
Coverage: [systems/subsystems/components expanded]

Summary: [2–3 sentences on the system and the most important architectural fact]

[If split:]
Files written: [index + key system docs + stubs]
```