code-documenter

# Code Documenter Skill

An intelligent documentation system that analyzes codebases and generates
thorough, comprehensive documentation tailored to your project type and audience
needs.

## Core Philosophy

**Documentation serves readers, not authors.** Every decision about structure,
depth, and content is evaluated from the reader's perspective:

- Will this help them understand?
- Will this help them succeed?
- Will this answer their questions?
- Does this earn its place?

**Comprehensive without overwhelm.** Thorough coverage of what matters, ruthless
cutting of what doesn't. The goal is complete, accurate, useful
documentation—not exhaustive documentation of every line of code.

**Documentation as code artifact.** Docs should be versioned, tested, and
maintained with the same rigor as code. They're not afterthoughts; they're
essential.

## When to Use This Skill

**Primary use cases:**

- After completing significant new work (epic, major feature, new app)
- When shipping an open source project
- When documentation has fallen out of sync with code
- When onboarding requires better documentation
- When setting up a new project properly

**Not for:**

- In-progress features (wait until stable)
- Code comments or docstrings (this generates external docs)
- API reference generation from code (use language-specific tools for that)

## Session Flow

### Mode Selection

The skill operates in two modes:

| Mode                   | When to Use                                     | Behavior                                          |
| ---------------------- | ----------------------------------------------- | ------------------------------------------------- |
| **Quick Mode**         | Incremental updates after new features          | Autonomous, fast, focused on what changed         |
| **Comprehensive Mode** | New projects, major overhauls, first-time setup | Collaborative, thorough, quality gates throughout |

**The skill will ask:** "Quick update or comprehensive documentation?"

### Phase 1: Multi-Agent Project Analysis

The skill deploys specialized analysis agents to understand your project:

```
Analysis Phase:
├─ Agent 1: Project Structure
│  └─ Scanning file tree, identifying project type, tech stack
├─ Agent 2: Code Surface Analysis
│  └─ Finding APIs, components, commands, exports
├─ Agent 3: Dependency Analysis
│  └─ Reviewing packages, frameworks, key dependencies
├─ Agent 4: Git History Analysis
│  └─ Analyzing commits since last doc update
├─ Agent 5: Existing Documentation Review
│  └─ Reading current docs, assessing state
└─ Synthesis: Generating documentation plan...
```

**Quick Mode:** Focused analysis on what changed since last update  
**Comprehensive Mode:** Full analysis of entire project

Each agent reports findings in structured format. You see everything happening.

### Phase 2: Documentation State Assessment

The skill compares code state vs. documentation state:

**If manifest exists (`.doc-state.json`):**

- Loads documentation state from last run
- Compares current code vs. last documented state
- Identifies what's changed (added/modified/removed)
- Shows you the documentation debt

**If no manifest:**

- First time documenting this project
- Will create fresh manifest after completion

**Key metrics shown:**

- **Health Score:** Current documentation health (0-100)
- **Coverage:** What % of public surface is documented
- **Freshness:** How current are docs vs. code
- **Debt:** What needs attention (prioritized)

### Phase 3: Audience & Scope Discovery

The skill asks:

1. **"Who needs these docs?"**
   - Developers only
   - Users only
   - Both developers and users

2. **"What depth of documentation?"**
   - **Standard:** Right-sized coverage (4,000-7,000 words)
   - **Deep:** Comprehensive with internals (8,000-12,000 words)

**Quick Mode:** Uses stored preferences from manifest  
**Comprehensive Mode:** Asks explicitly, shows examples

### Phase 4: Documentation Boundaries

The skill proposes what should be documented:

```
Based on my analysis of your Express + PostgreSQL API:

PUBLIC SURFACE (Always Document)
├─ 12 API endpoints in /routes
├─ Database schema (3 tables)
├─ 14 environment variables
└─ Authentication flow

INTERNAL IMPLEMENTATION (Recommended for Deep)
├─ 6 middleware functions
├─ Error handling patterns
└─ Database migration strategy

INFRASTRUCTURE (Essential for all levels)
├─ Docker setup
├─ CI/CD pipeline
└─ Deployment process

EXCLUDED (Recommend skip)
├─ Test files (obvious from names)
├─ Build scripts (standard tooling)
└─ Internal helpers (<10 lines each)

Adjust these boundaries? [approve/modify]
```

You approve or adjust before documentation generation begins.

### Phase 5: Documentation Plan Presentation

The skill presents a complete plan:

```
DOCUMENTATION PLAN

Structure:
└─ /docs
   ├─ developers/
   │  ├─ api.md (API endpoint reference)
   │  ├─ architecture.md (System design + diagrams)
   │  ├─ contributing.md (How to contribute)
   │  ├─ deployment.md (Deploy & operate)
   │  ├─ troubleshooting.md (Common issues)
   │  ├─ examples/ (12 runnable examples)
   │  └─ adr/ (4 architecture decisions)
   ├─ users/
   │  ├─ getting-started.md (Quick start guide)
   │  ├─ features.md (Feature overview)
   │  ├─ troubleshooting.md (User-facing issues)
   │  └─ examples/ (5 user examples)
   ├─ CHANGELOG.md (Documentation change log)
   └─ documentation-map.md (Navigation guide)

Files to update:
- README.md (complete rewrite, progressive disclosure)
- docs/developers/api.md (2 new endpoints, 1 modified)
- docs/CHANGELOG.md (new entry)

Files to create:
- docs/adr/004-caching-strategy.md (new decision)
- docs/developers/examples/pagination.js (new example)

Files to remove:
- docs/developers/legacy-auth.md (endpoint removed)

Estimated scope: ~5,200 words total
Target health score: 92/100

Proceed? [yes/adjust scope/abort]
```

**Comprehensive Mode:** Review and approve before generation  
**Quick Mode:** Brief preview, option to