init-doc

name	init-doc
description	Generate comprehensive project documentation from scratch by analyzing source code. Use when a project has no documentation, incomplete documentation, or legacy documentation that needs to be fully replaced. Creates a README.md hub and docs/ folder with detailed topic files. Works with any language, framework, or stack. This is a full documentation bootstrap — not incremental updates (use update-doc for that).
allowed-tools	Read, Edit, Write, Grep, Glob, Bash
disable-model-invocation	true
argument-hint	'refactor' to restructure existing docs, or specific focus/context

init-doc

Generate comprehensive project documentation by deeply analyzing source code. Works with any language, framework, or stack.

Output Standard

Documentation produced by this skill:

1. README.md at project root — the documentation hub linking to all docs/ files
2. docs/ folder — detailed topic files, one per concern
3. Gotchas documentation — always created; captures non-obvious behavior and pitfalls:
   • docs/gotchas.md — thin hub/index (~30-50 lines) linking to each domain file with a one-line description
   • docs/gotchas/<domain>.md — one file per domain (e.g., database.md, deployment.md, frontend.md); domains are determined during Phase 2 from the project's actual subsystems

Gotchas Structure

The gotchas hub (docs/gotchas.md) is purely navigational — no gotcha content lives here:

# Gotchas

Lessons learned the hard way so we don't repeat them.

## Table of Contents
- [Database](gotchas/database.md) — Migrations, queries, schema design
- [Deployment](gotchas/deployment.md) — Pulumi, CloudFront, Lambda, SES
- ...

Each domain file is a standalone document: h1 heading, linked TOC, full gotcha entries with code examples. Cross-link between domain files when a gotcha spans domains.

Size Guardrails

Each documentation file has a soft line limit. Exceeding it signals the file covers multiple concerns and should be split.

File	Soft limit	Rationale
README.md	750 lines	Hub document — must be self-sufficient as entry point, especially for monorepos
docs/*.md	750 lines	Technical docs need room for code examples, but the single-concern principle must hold
docs/gotchas.md (hub)	50 lines	Navigational index only — all content lives in domain files

These limits are guardrails, not hard walls. A 780-line file that is genuinely about one cohesive topic is fine. But a file that keeps growing across maintenance cycles is a file that needs splitting. The primary driver is always single-concern coherence — line count is the check-yourself moment.

Table of Contents

Every documentation file produced — README.md and every docs/ file — MUST include a Table of Contents immediately after the h1 heading, granular up to h4. No exceptions.

The TOC must use linked markdown list format with anchor links so that both LLMs and humans can navigate to specific sections without reading the full file:

## Table of Contents
- [Section Name](#section-name)
  - [Subsection](#subsection)
    - [Detail](#detail)

Cross-Linking

All docs must be cross-linked so init-context can recursively traverse the full knowledge graph, and structured so update-doc can maintain them going forward.

Process

Mode Detection

Check $ARGUMENTS for a named mode:

Argument	Mode	Description
refactor	Refactor	Restructure existing documentation without source code analysis
(anything else)	Normal	Full documentation bootstrap from source code analysis

• Normal mode: Execute Phases 1-5 below.
• Refactor mode: Skip to Refactor Mode.

Phase 1: Reconnaissance

Execute the full reconnaissance process documented in ../init-mission/reconnaissance.md. This produces a structured project summary covering project identity, shape, infrastructure, and existing documentation.

Optional: Mission Document

After completing reconnaissance, offer the user the option to create a mission document:

"Before I dive into the codebase, would you like to create a mission document (docs/mission.md)? It captures your project's vision, values, non-goals, users, and UX compass through a short interview. This gives the documentation a strategic foundation — I can reference it to write docs that reflect what the project is actually trying to achieve, not just what the code does. It's optional and takes about 5 minutes. We can also do this later."

• If the user accepts: Invoke /init-mission and pass the reconnaissance results as the argument. Wait for init-mission to complete before continuing to Phase 2.
• If the user declines: Continue to Phase 2 as normal.

Phase 2: Deep Analysis

Read source code systematically. Focus on understanding behavior, not exhaustive line-by-line reading.

1. Start at entry points — Read main modules to understand the core purpose and execution flow
2. Trace data flow — Follow how data enters the system, transforms, and exits
3. Map APIs and interfaces — Endpoints, routes, CLI commands, exported functions, event handlers
4. Understand configuration — Environment variables (check .env.example or equivalent), config files, feature flags
5. Read tests — Tests reveal expected behavior, edge cases, and integration points
6. Identify patterns — Architecture style, error handling, auth model, logging, naming conventions
7. Note gotchas — Non-obvious behavior, surprising design choices, workarounds, known limitations
8. Check scripts — Build, test, deploy, and utility scripts in package manifests or Makefiles
9. Classify gotchas by domain — Group the gotchas noted in step 7 by the project subsystem they belong to. Each group becomes a docs/gotchas/<domain>.md file. Use concrete domain names derived from the project's actual structure (e.g., database, deployment, frontend, api), not generic categories.

Existing gotchas awareness: If docs/gotchas/ already exists with domain files, treat the existing structure as authoritative — add new gotchas to existing domain files or propose new domain files. If only a monolithic docs/gotchas.md exists (no docs/gotchas/ directory), the plan in Phase 3 must include splitting it into hub + domain files.

Phase 3: Documentation Plan

STOP. Do NOT write any files until the user approves this plan.

1. Propose the docs/ file list — Only files relevant to this project. Use the topic catalog below.
2. Outline each file — Draft the section headings for README.md and each docs/ file
3. Propose the gotchas structure — List the domain files to create under docs/gotchas/, with the gotchas mapped to each domain
4. Estimate sizes — Include a rough line estimate for each proposed file. If any file is projected to exceed 750 lines, proactively split it in the plan rather than discovering the issue after writing.
5. Note what will be replaced — If legacy docs exist, explicitly list what will be removed
6. Present the plan and wait for user approval

Topic Catalog

Only create docs/ files that are warranted. Common topics:

File	When to create
docs/architecture.md	Multi-component systems, non-trivial data flow, service interactions
docs/database.md	Schemas, migrations, data models, seed scripts
docs/api.md	REST, GraphQL, gRPC, or WebSocket endpoints
docs/cli.md	CLI tools with commands, flags, and usage patterns
docs/deployment.md	Non-trivial deploy process, CI/CD pipelines, environments
docs/configuration.md	Many env vars, config files, secrets management
docs/testing.md	Complex test setup, multiple test types, test data
docs/infrastructure.md	IaC resources, cloud services, networking, scaling
docs/gotchas.md + docs/gotchas/*.md	Always created — hub index + per-domain gotcha files
docs/mission.md	Created by init-mission — business vision, values, non-goals, users, UX compass

Create additional topic files if the project demands it (e.g., docs/auth.md, docs/etl.md). Never create empty shells — every file must have substantive content.

Phase 4: Writing

After user approves the plan:

1. Create docs/ directory if it doesn't exist
2. Create docs/gotchas/ directory and write gotchas domain files:
   • One file per domain identified in Phase 2 step 9
   • Each file: h1 heading, linked TOC (up to h4), full gotcha entries with code examples
   • Cross-link between domain files when a gotcha references another domain
3. Write docs/gotchas.md hub — thin index (30-50 lines) with:
   • h1 heading and one-line description ("Lessons learned the hard way so we don't repeat them.")
   • TOC section listing each domain file as a link with a one-line summary
   • No gotcha content in this file — it is purely navigational
4. Write other docs/ files — each topic file with:
   • Clear heading hierarchy (h1 through h4 max)
   • Table of Contents (up to h4) immediately after the h1
   • Cross-links to related docs/ files where relevant
   • Concrete examples from the actual codebase — not generic placeholders
5. Write README.md last — the hub document structured as:
   • Project name (h1) and one-line description
   • Table of Contents (up to h4), using linked markdown list format with anchor links
   • Overview — what the project does, why it exists, who it's for
   • Getting Started — prerequisites, installation, configuration, running
   • Project Structure — brief annotated directory layout. For monorepos, include a per-sub-project orientation (one paragraph per sub-project explaining its purpose, stack, and entry point) so readers know which docs/ file to load next.
   • Documentation — links to every docs/ file with a one-line summary per link. If docs/mission.md exists, its entry must include a brief explanation of how it supports decision-making at two levels:
     • Proactive (before implementation) — when a bug fix or feature request comes in, the mission provides the lens through which to interpret and approach it. This context can steer the implementation in a direction that aligns with the project's ultimate goals — a direction that would not emerge without the mission.
     • Reactive (when facing multiple solutions) — when multiple valid approaches exist, the mission provides enough context to choose the best path without asking the user. The AI should only escalate to the user when there is a genuine conflict or ambiguity that the mission cannot resolve — this should be the exception, not the rule.

Phase 5: Validation

After writing all documentation:

1. Verify cross-links — every docs/ file must be linked from README.md; cross-links between docs/ files must point to real files
2. Check file sizes — verify README.md is under 750 lines, each docs/ file is under 750 lines, and the gotchas hub is under 50 lines. If any file exceeds the guardrail, split it.
3. Verify gotchas integrity — the hub exists, every domain file in docs/gotchas/ has a corresponding entry in the hub, and every hub entry links to an existing domain file
4. Spot-check accuracy — re-read 2-3 key source files and verify documentation matches
5. Summarize — list what was created and what was removed

---

Refactor Mode

Triggered by /init-doc refactor. Restructures existing documentation according to best practices without reading source code. Trusts existing content is accurate.

Refactor Phase 1: Structural Scan

Light scan — no source code reading:

1. Scan project structure — Run ls on the project root to understand directory layout and identify project domains/subsystems
2. Read ALL existing documentation — README.md, every file in docs/ (excluding docs/manual/)
3. Inventory what exists — File list, line counts, presence of TOCs, cross-link status
4. Identify domains for gotchas — From the existing gotchas content (not source code), group gotcha sections by the subsystem they describe. Each group becomes a docs/gotchas/<domain>.md file.

Refactor Phase 2: Plan

STOP. Do NOT write any files until the user approves this plan.

1. Propose the restructured file list:
   • Which existing files need splitting (over 750 lines)
   • The docs/gotchas/ domain files to create, with the proposed content mapping (which sections from the current gotchas go where)
   • The new docs/gotchas.md hub structure
2. Outline each new or modified file — draft section headings
3. Estimate sizes — line estimates for each proposed file
4. Show what changes — explicitly list files that will be modified, created, or split
5. Present the plan and wait for user approval

Refactor Phase 3: Execute

After user approves the plan:

1. Create docs/gotchas/ directory
2. Write domain files — For each domain identified in Refactor Phase 1 step 4:
   • Create docs/gotchas/<domain>.md with h1 heading, linked TOC, and the gotcha entries moved from the original file
   • Preserve all existing content verbatim — do not rewrite, verify, or remove anything
   • Add cross-links between domain files when a gotcha references another domain
3. Rewrite docs/gotchas.md as a thin hub (30-50 lines):
   • h1 heading and one-line description
   • TOC with links to each domain file and a one-line summary per domain
4. Fix all affected cross-links — update any docs/ file that linked to a specific section in the old gotchas.md to point to the new domain file
5. Apply general restructuring — For any other file over 750 lines, split by sub-concern
6. Fix TOCs — Regenerate TOCs in all modified files
7. Update README.md — update the gotchas entry in the Documentation section to reflect the hub + domain structure

Refactor Phase 4: Validate

1. Verify the hub — docs/gotchas.md is under 50 lines, all links resolve to real domain files
2. Verify domain files — each has a linked TOC, each is under 750 lines, no content was lost from the original
3. Verify cross-links — all references to gotchas.md#section-anchor in other docs/ files now point to the correct domain file
4. Check file sizes — all files under their respective guardrails
5. Summarize — list what was created, modified, and how content was redistributed

---

Constraints

• NEVER modify CLAUDE.md, MEMORY.md, .claude/, specs/, or docs/manual/
• NEVER fabricate information — if something cannot be determined from source code, say so explicitly
• NEVER write documentation for code you haven't read (except in Refactor mode, which restructures existing docs)
• NEVER skip Phase 3 / Refactor Phase 2 — always get user approval before writing any files
• NEVER create empty documentation files
• NEVER omit a Table of Contents — every file (README.md and every docs/ file) must have a linked markdown TOC immediately after its h1, granular up to h4
• NEVER let a file exceed its size guardrail without splitting — README.md at 750 lines, docs/ files at 750 lines, gotchas hub at 50 lines
• Write for a developer who knows nothing about this project
• Use the project's actual terminology, variable names, and conventions — not generic placeholders
• Include concrete examples from the actual codebase — not generic placeholders or hypothetical snippets
• Keep each docs/ file focused on a single concern — split rather than merge