---
name: roll-doc
license: MIT
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(date:*,find:*,stat:*,wc:*)"
description: "Legacy project documentation automation. Scans all docs, builds/updates docs/INDEX.md, identifies undocumented modules, and generates draft fills for gaps. Works on any project."
---

# roll-doc

Four-phase legacy documentation automation: scan → index → gap analysis → fill.

Works on any project root. No manual mode switching — reads the project state and decides what to do.

## When to Use

- Starting to work on a legacy project with scattered or missing documentation
- `docs/INDEX.md` is out of date or doesn't exist yet
- `roll-.dream` Scan 6 flagged undocumented modules (REFACTOR entry referencing roll-doc)
- You want a complete picture of what's documented and what isn't

## When Not to Use

- The project has up-to-date, maintained docs — no need to rebuild the index
- You need authoritative documentation reviewed and approved (drafts only; human reviews and commits)
- You want to write a specific known doc from scratch — write it directly

## Invocation

```
$roll-doc              # Full four-phase run
$roll-doc --dry-run    # Phases 1–2 only; print Phase 3 plan without writing any files
$roll-doc --force      # Re-generate drafts even for existing files
```

## Phase 1 — Scan & Index

Scan the project root for all `*.md` files and known convention files.

**Exclusions — never scan these directories:**

```
node_modules/   .git/   dist/   build/   .shared/   docs/dream/   docs/briefs/
```

**Convention files — detect by filename anywhere in the tree:**

```
AGENTS.md   CLAUDE.md   GEMINI.md   CONVENTIONS.md   CONTRIBUTING.md
ARCHITECTURE.md   ADR-*.md
```

**Classification rules:**

| Category | Criteria |
|----------|----------|
| `guide` | Path under `docs/guide/` |
| `domain` | Path under `docs/domain/` |
| `convention` | Filename matches convention markers list above |
| `module` | File is `<dir>/README.md` for a source directory |
| `stray` | None of the above (top-level, unorganized, or orphaned) |

**Output — produce/update `docs/INDEX.md`:**

```markdown
# Documentation Index

> Auto-generated by roll-doc on YYYY-MM-DD. Edit individual docs, not this file.

## Index

| Path | Title | Category | Last Modified |
|------|-------|----------|---------------|
| docs/guide/en/loop.md | Loop User Guide | guide | 2026-05-01 |
| AGENTS.md | Agent Conventions | convention | 2026-04-28 |

## Coverage Summary

- Total docs indexed: N
- By category: guide (N) / domain (N) / convention (N) / module (N) / stray (N)

## Gap Report

Directories with ≥3 source files and no linked documentation:

| Directory | Source Files | Missing Doc |
|-----------|-------------|-------------|
| src/commands/ | 8 | README.md |
```

`docs/INDEX.md` is always overwritten on each run — it is a derived artifact, not authoritative content.

## Phase 2 — Gap Analysis

Walk every directory (applying Phase 1 exclusions):

1. Count non-hidden, non-`.md` source files directly in the directory
2. If count ≥ 3 AND no `README.md` in that directory AND no `docs/INDEX.md` entry links to it → **module gap**

**Special gaps (checked once per project):**
- No `docs/domain/` directory or empty → gap: `docs/domain/context-map.md`
- No `CONVENTIONS.md` or `docs/CONVENTIONS.md` exists → gap: `docs/CONVENTIONS.md`

**Threshold**: directories with ≥ 3 source files (default). Tune by editing the skill.

Record all gaps — they become Phase 3 input.

## Phase 3 — Fill

**Skip this phase entirely when:**
- `--dry-run` was passed (print the fill plan to stdout, write nothing)
- Phase 2 found zero gaps

**Idempotency rule**: Without `--force`, re-running when no new gaps exist is a **no-op** — no files are written, no existing drafts are modified.

For each gap:
1. Read up to 20 source files from the target directory to infer module purpose, key exports, dependencies, and configuration patterns
2. Generate a draft document at the conventional location (see table below)
3. **Skip if the target file already exists**, unless `--force` was passed

**Draft locations by gap type:**

| Gap Type | Draft Location |
|----------|---------------|
| Module with no README | `<dir>/README.md` |
| No `docs/domain/` entries | `docs/domain/context-map.md` |
| No conventions doc | `docs/CONVENTIONS.md` |

**Every generated file starts with this exact header line:**

```
> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
```

**Minimum draft content:**

- Module README: purpose (1–2 sentences), key files with one-line descriptions, dependencies (imports from / depended on by)
- Context map: bounded contexts identified in the project, their responsibilities, relationships
- Conventions: detected patterns — ENV vars, naming conventions, repeated file structure templates

Do not fabricate details — infer only from source files actually read.

## Phase 4 — Report

After all phases complete, output a summary:

```
📚 roll-doc complete

Phase 1 — Index
  N docs scanned, docs/INDEX.md updated
  Categories: guide(N) domain(N) convention(N) module(N) stray(N)

Phase 2 — Gaps
  N undocumented module directories found
  N special gaps (domain map / conventions)

Phase 3 — Fill
  N drafts generated: [list of paths]
  N skipped (already exist; use --force to regenerate)

📋 Review priority (largest / most active modules first):
  1. src/commands/README.md — 8 source files
  2. docs/CONVENTIONS.md — 6 patterns detected
```

If no gaps were found:

```
✅ roll-doc: no gaps found. docs/INDEX.md updated.
```

If `--dry-run`:

```
🔍 roll-doc --dry-run: N drafts would be generated (nothing written).
```

## Rules

- Never modify existing documentation files — only generate new drafts
- `docs/INDEX.md` is the only existing file that may be overwritten (derived artifact)
- Draft files are never committed by this skill — human reviews and commits them
- Works on any project; always read project structure before acting
- Do not fabricate module details — infer only from source files actually read