---
name: document
description: |
  Bottom-up codebase documentation skill. Analyzes existing code from modules up through components
  to architecture, then retrospectively derives problem/restrictions/acceptance criteria.
  Produces the same _docs/ artifacts as the problem, research, and plan skills, but from code
  analysis instead of user interview.
  Trigger phrases:
  - "document", "document codebase", "document this project"
  - "documentation", "generate documentation", "create documentation"
  - "reverse-engineer docs", "code to docs"
  - "analyze and document"
category: build
tags: [documentation, code-analysis, reverse-engineering, architecture, bottom-up]
disable-model-invocation: true
---

# Bottom-Up Codebase Documentation

Analyze an existing codebase from the bottom up — individual modules first, then components, then system-level architecture — and produce the same `_docs/` artifacts that the `problem` and `plan` skills generate, without requiring user interview.

## File Index

| File | Purpose |
|------|---------|
| `workflows/full.md` | Full / Focus Area / Resume modes — Steps 0–7 (discovery through final report) |
| `workflows/task.md` | Task mode — lightweight incremental doc update triggered by task spec files |
| `references/artifacts.md` | Directory structure, state.json format, resumability, save principles |

**On every invocation**: read the appropriate workflow file based on mode detection below.

## Core Principles

- **Bottom-up always**: module docs → component specs → architecture/flows → solution → problem extraction. Every higher level is synthesized from the level below.
- **Dependencies first**: process modules in topological order (leaves first). When documenting module X, all of X's dependencies already have docs.
- **Incremental context**: each module's doc uses already-written dependency docs as context — no ever-growing chain.
- **Verify against code**: cross-reference every entity in generated docs against actual codebase. Catch hallucinations.
- **Save immediately**: write each artifact as soon as its step completes. Enable resume from any checkpoint.
- **Ask, don't assume**: when code intent is ambiguous, ASK the user before proceeding.

## Context Resolution

Fixed paths:

- DOCUMENT_DIR: `_docs/02_document/`
- SOLUTION_DIR: `_docs/01_solution/`
- PROBLEM_DIR: `_docs/00_problem/`

Optional input:

- FOCUS_DIR: a specific directory subtree provided by the user (e.g., `/document @src/api/`). When set, only this subtree and its transitive dependencies are analyzed.

Announce resolved paths (and FOCUS_DIR if set) to user before proceeding.

## Mode Detection

Determine the execution mode before any other logic:

| Mode | Trigger | Scope | Workflow File |
|------|---------|-------|---------------|
| **Full** | No input file, no existing state | Entire codebase | `workflows/full.md` |
| **Focus Area** | User provides a directory path (e.g., `@src/api/`) | Only the specified subtree + transitive dependencies | `workflows/full.md` |
| **Resume** | `state.json` exists in DOCUMENT_DIR | Continue from last checkpoint | `workflows/full.md` |
| **Task** | User provides a task spec file AND `_docs/02_document/` has existing docs | Targeted update of docs affected by the task | `workflows/task.md` |

After detecting the mode, read and follow the corresponding workflow file.

- **Full / Focus Area / Resume** → read `workflows/full.md`
- **Task** → read `workflows/task.md`

For artifact directory structure and state.json format, see `references/artifacts.md`.