ix-infrastructure/ix-gemini-plugin/ix-docs

Goal

Produce documentation that helps a new engineer understand the system quickly.

If Ix is unavailable (tool calls fail, or ix_health() reports the backend unreachable), this skill cannot proceed without the graph.

Core model

Every ix-docs run produces two layers:

1. Narrative layer (always first) — human-readable, onboarding-focused
2. Reference layer (always present, but selective) — compressed summaries of important components

Mode: default = narrative-heavy; --full = deeper coverage. Style: --style narrative (default) / --style reference / --style hybrid.

Non-negotiable rules

1. Graph first — start with ix_subsystems, ix_overview, ix_rank, ix_explain
2. Importance-weighted — expand detail by centrality, risk, coupling
3. Selective low-level detail — never exhaustive
4. No raw dumps — summarize tool results
5. No redundancy — group repeated patterns
6. Code reads are rare — default: max 2; full: max 5

Preferred path — one call

For a named target, call ix_context first and use its evidence as the skeleton of the narrative layer:

ix_context({ target: $ARGUMENTS })

Supplement with the phases below for --full coverage.

Phases

Phase 1 — Scope

Call in parallel:

• ix_stats() — graph size, file count
• ix_subsystems() — top-level architecture

Phase 2 — Architecture

Call in parallel:

• ix_overview({ target: $ARGUMENTS })
• ix_rank({ by: "dependents", kind: "class", top: 10 })

Phase 3 — Behavior

Call ix_explain({ symbol: <component> }) for the most important components (top 3-5 by rank).

Phase 4 — Relationships

For key components:

• ix_callers({ symbol: <component> })
• ix_callees({ symbol: <component> })
• ix_depends({ symbol: <component>, depth: 2 })

Phase 5 — Risk

Call: ix_impact({ target: $ARGUMENTS })

Phase 6 — Health

Call: ix_smells()

Phase 7 — Optional reads (max 2-5 source reads for --full)

Output structure

# [Target] — Documentation
 
## Part 1 — Narrative
1.Overview
2.Architecture
3.How It Works
4.Key Components
5.Dependencies & Relationships
6.Risk & Complexity
7.How to Work With This Repo
8.Where to Go Deeper
 
## Part 2 — Selective Reference
-Module Summary
-Class / Service Summary
-Method Summary (--full only, key classes only)