eli-doc

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] |