eli-doc

name	eli-doc
description	Generates a plain-language glossary (ELI5.md) for the current codebase. Trigger when the user says "/eli-doc", "generate eli5 docs", "make a plain-language glossary", "explain this codebase simply", "create eli5 documentation", or "document this for beginners".

ELI5 Doc — Generate Plain-Language Codebase Glossary

Scan the current codebase and write ELI5.md — a plain-language guide to everything in it.

Steps

1. Discover the codebase

# Get a high-level picture
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" \
  -o -name "*.rs" -o -name "*.rb" -o -name "*.java" -o -name "*.cs" \) \
  -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
  -not -path "*/build/*" | head -60

Also check for: README.md, package.json, pyproject.toml, Cargo.toml, go.mod to understand the project's purpose.

2. Check eli5 level

cat .claude/eli5-state.json 2>/dev/null || echo "none"

Default to eli-adult level for docs (smart non-expert reader) unless a different level is currently active or the user specifies one.

3. Identify concepts to document

From the codebase, extract:

• What the project does (1-paragraph overview)
• Key concepts — domain terms, patterns, architectural decisions
• Main components — important files, classes, modules (top 10–15)
• How data flows — what comes in, what happens, what comes out
• Jargon the codebase uses — tech terms that appear frequently

4. Write ELI5.md

Use this structure:

# [Project Name] — Plain Language Guide

> Generated by eli5-mode. Level: [current level]. Updated: [date]

## What this project does

[2–3 sentences. Analogy-first. No jargon. What problem does it solve?]

## The big picture

[Optional: a flow diagram in words — "First X happens. Then Y. Finally Z."]

## Key concepts

### [Concept 1]
[Analogy-first explanation at the current level. 2–4 sentences.]

### [Concept 2]
[Same format]

[...continue for all key concepts...]

## Main files and what they do

| File | What it does (plain language) |
|---|---|
| `src/index.ts` | [plain description] |
| `src/auth.ts` | [plain description] |

## How data moves through the system

[Narrative walkthrough. Use concrete analogies. Walk through a typical request/action.]

## Words this project uses a lot

| Term | What it really means |
|---|---|
| [term] | [plain-language definition via analogy] |

5. Confirm

"Written ELI5.md — [N] concepts, [M] files documented at [level] level."

Team mode: /eli-doc --team

When --team is specified, produce a version designed to be committed to the repo as an onboarding artifact:

• Add a "New hire start here" section at the top with the 3 most important files to read first
• Include a "Gotchas" section: 3–5 things that trip up newcomers in this specific codebase
• Add a "Glossary" section: every domain-specific or project-specific term, plain-language only
• Output filename: ELI5.md (same) — but add a header note: > Intended for new contributors. Keep this up to date.
• Suggest: "Commit this as ELI5.md in the repo root — it'll be there for every new hire."

Important

• Stay at the eli5 level throughout. No technical jargon in the output.
• Accuracy matters: read actual files before describing them. Don't invent.
• If the codebase is large (>50 files), focus on the most-referenced files and entry points.
• Check ~/.claude/skills/eli5-mode/references/analogy-bank.md for ready-to-use analogies.