ix-docs

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 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 | **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 command output - Never paste command logs - Never dump full file inventories, all callers, or all methods 5. **No redundancy** - Group repeated patterns - If several modules have the same role, summarize the pattern once - If an entity appears in multiple rankings, explain it once and cross-reference 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; never read whole files for this skill --- ## Coverage policy Use the following ranking factors to decide what gets expanded: 1. **Centrality**: `ix rank`, 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 - symbol or small component: focus on the target, its immediate collaborators, and the surrounding subsystem **Full mode** - repo or large system: cover all major systems, expand the top 5-8 by importance, create short stubs for lower-ranked ones when split output is large - subsystem or module: expand the top 8-12 entities, add method summaries for the top 3-5 classes or services only When a repo is very large, prefer: - full docs for the highest-ranked systems - short overview stubs for the lower-ranked remainder --- ## Command strategy Do not run every command mechanically. Reuse earlier results and stop when additional depth would not materially improve the documentation. ### Phase 1 — Scope Always start with: ```bash timeout 60s ix stats --format llm timeout 60s ix subsystems --format llm timeout 60s ix subsystems --list --format llm ``` If `TARGET` is not obviously the whole repo: ```bash timeout 60s ix locate "$TARGET" --limit 5 --format llm ``` Resolve whether the target is: - repo - top-level system - subsystem - module or file - class, service, or symbol If ambiguous, resolve it before proceeding. ### Phase 2 — Architecture Use the graph to identify systems, subsystem boundaries, and the most important modules. Common commands: ```bash timeout 60s ix overview "$TARGET" --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 `TARGET` is the whole repo, skip `ix overview "$TARGET"` and rely on the pre-run subsystem data plus the rank results. Additional commands by scope: For repo or system targets: ```bash timeout 60s ix subsystems "$TARGET" --format llm timeout 60s ix subsystems "$TARGET" --explain ``` For module or file targets: ```bash timeout 60s ix contains "$TARGET" --format llm timeout 60s ix imports "$TARGET" --format llm ``` Full mode: - raise rank budgets to 20 - inspect the most important systems first, never alphabetically - for the top systems, collect `ix subsystems <system>` and `ix subsystems <system> --explain` ### Phase 3 — Behavior This phase answers **how the system works**. Use: ```bash timeout 60s ix explain "$TARGET" --format llm ``` Also run `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: - run **one** `ix trace` only if the main execution flow is still unclear after `ix explain` Describe: - request or data lifecycle - orchestration paths - subsystem handoffs - where decisions, transformation, or state changes happen Do not narrate every edge in a trace. ### Phase 4 — Relationships Map the important dependencies and coupling points. Use: ```bash timeout 60s ix callers "$TARGET" --limit 20 --format llm timeout 60s ix callees "$TARGET" --limit 15 --format llm timeout 60s ix depends "$TARGET" --depth 2 --format llm ``` If `TARGET` is the whole repo, do not run repo-level callers or callees. Instead, run these commands for the top-ranked boundary components, orchestrators, or subsystem entry points and summarize the cross-subsystem edges they reveal. For repo or large system targets, focus on: - cross-system relationships - shared infrastructure - boundary modules - the most central components from the rank results When counts are large: - group callers by subsystem - summarize repeated patterns - never list more than 15 similar names individually ### Phase 5 — Risk Always run: ```bash timeout 60s ix impact "$TARGET" --format llm ``` Full mode: - also run `ix impact` for the top 2-5 high-centrality entities Use this phase to populate: - fragile integration points - change-sensitive modules - shared infrastructure warnings - parts of the system that need careful testing ### Phase 6 — Health Use: ```bash timeout 60s ix smells --format llm ``` If the target is smaller than a full repo, scope it when supported: ```bash timeout 60s ix smells --path "$TARGET" --format llm ``` Prioritize: - god modules - highly coupled regions - orphaned or poorly connected components - subsystems with weak boundaries Group health issues by subsystem, not as a flat dump. ### Phase 7 — Optional reads 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` Use: ```bash timeout 60s ix read <symbol> --format llm ``` Do not summarize implementation line-by-line. Extract only the behavior needed to clarify the docs. --- ## Writing rules by style ### `--style narrative` - lead with prose - each narrative section should explain how to think about the system - reference layer should stay compressed ### `--style reference` - still keep the narrative layer first, but tighten it to short paragraphs - use more headings, bullets, and compact summaries - make the reference layer more prominent than in narrative mode ### `--style hybrid` - full narrative layer - fuller reference layer - best option for `--full`, onboarding docs, and handoff docs --- ## Output structure The document should feel like real documentation, not an investigation transcript. Use this 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 ### 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 (orchestrator, boundary, helper, store, adapter, etc.) - 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 - role in the system, not implementation detail ``` ### Reference layer rules - include only important modules or classes - if a module is obvious and low-risk, omit it - if multiple entities share a pattern, summarize the pattern once - do not add method summaries in default mode unless the user explicitly asks for reference-heavy output --- ## Split output Use split output when: - `--split` is passed, or - `FULL=true` and the repo is large enough that one doc would become unwieldy Recommended structure: ```markdown <OUT_DIR>/ index.md <system-1>.md <system-2>.md ... <lower-ranked-system>-stub.md ``` ### `index.md` Should contain: - overall overview - top-level architecture - the most important cross-system flows - repo navigation guidance - links to the per-system docs ### Per-system docs Each system doc should contain: - the full narrative structure - a selective reference section for that system ### Stubs For lower-ranked systems, create short stubs instead of full docs: - one-paragraph overview - top 3 important components - one risk note - clear instruction to rerun `ix-docs <system> --full` if deeper coverage is needed --- ## Success criteria The output is successful if: - a new engineer can understand the system quickly - an LLM can reason about the system without rereading dozens of files - the important parts are obvious - the main execution flow is understandable - guidance for deeper exploration is explicit The output has failed if: - it reads like a dump - low-level detail dominates the document - important components are buried - every module gets equal treatment - it gives no practical guidance on where to start --- ## Post-write confirmation After writing the file or files, confirm: ```text 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] ```