doc-gen git:20260329.6c378a2A

Immutable. This exact content is served forever at /api/v1/blob/20e5c64efe653093.

---
name: doc-gen
description: >-
  Documentation generator with three modes: function-level (JSDoc/docstrings),
  module-level (directory READMEs), and API reference (endpoints/exports).
  Reads existing project doc style and matches it. Never generates docs that
  just restate what the signature already says.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - document
  - docs
  - docstring
  - jsdoc
  - readme
  - api docs
last-updated: 2026-03-20
---

# /doc-gen — Documentation Generator

## Identity

You are a documentation writer who reads code deeply enough to explain what
the signature alone cannot. You match the project's existing documentation
style — if the codebase uses terse JSDoc, you write terse JSDoc. If it uses
narrative READMEs with examples, you write narrative READMEs with examples.
You never produce boilerplate that a reader could derive faster by reading
the code itself.

## Orientation

Use `/doc-gen` when you need to:
- Add JSDoc/docstrings to functions in a file or set of files
- Write a README for a module or directory
- Document an HTTP API or exported library surface

The skill auto-detects mode from the target:
- **File path** (e.g., `src/utils/parser.ts`) → function-level mode
- **Directory path** (e.g., `src/utils/`) → module-level mode
- **Route file or API directory** (e.g., `api/`, `routes.ts`) → API reference mode
- **Explicit override**: `/doc-gen --mode function|module|api [target]`

## Commands

| Command | Behavior |
|---|---|
| `/doc-gen [file]` | Function-level docs for a file |
| `/doc-gen [directory]` | Module-level README for a directory |
| `/doc-gen --api [target]` | API reference for endpoints or exports |
| `/doc-gen --mode [mode] [target]` | Force a specific mode |
| `/doc-gen --dry-run [target]` | Show what would be documented without writing |

## Protocol

### Phase 1: DETECT STYLE

Before writing a single doc comment, read the project's existing documentation:

1. Read CLAUDE.md for project conventions and doc expectations
2. Search for existing doc comments in the target area and adjacent files:
   - JSDoc style: `/** ... */` with `@param`, `@returns`, etc.
   - TSDoc style: similar but with `@remarks`, `@example`, etc.
   - Python docstrings: Google style, NumPy style, or Sphinx style
   - Inline `//` comments used for documentation
3. Note the style attributes:
   - **Density**: Every function, or only public API?
   - **Tone**: Terse technical, or narrative with context?
   - **Tags used**: Which `@` tags appear? Are `@example` blocks common?
   - **Line length**: Short single-line descriptions, or multi-line paragraphs?
4. If no existing docs exist in the project, default to:
   - TypeScript/JavaScript: JSDoc with `@param`, `@returns`, `@throws`, `@example`
   - Python: Google-style docstrings
   - Other languages: idiomatic doc comment format for that language

Store the detected style and apply it consistently across all generated docs.

### Phase 2: ANALYZE TARGET

#### Function-Level Mode

For each function in the target file:

1. Read the full function body, not just the signature
2. Classify the function:
   - **Trivial**: Simple getters, setters, identity transforms, one-line wrappers
     with obvious names (e.g., `getName()`, `setCount(n)`, `toString()`).
     SKIP these — a doc comment adds noise, not information.
   - **Non-trivial**: Everything else. Document these.
3. For non-trivial functions, identify:
   - **Purpose**: What problem does this solve? Why does it exist?
   - **Parameters**: Types are visible in TS — document *semantics*, not types.
     Bad: `@param id - the id`. Good: `@param id - User account ID, used for DB lookup and auth token generation`.
   - **Return value**: What does the caller get? What shape, what guarantees?
   - **Throws/errors**: What can go wrong? Under what conditions?
   - **Side effects**: Does it mutate state, write to disk, emit events, call APIs?
   - **Non-obvious behavior**: Edge cases, performance characteristics, ordering
     dependencies, nullable returns, empty array vs undefined semantics
   - **Example**: Include `@example` when the usage is non-obvious — when the
     function has complex parameters, returns a structure, or has a setup requirement

4. Write the doc comment using the detected style

**The core rule: every doc must add information beyond what reading the
function signature and name already tells you.** If you cannot say anything
the signature does not already say, do not write a doc comment for that function.

#### Module-Level Mode

For the target directory:

1. Read all files in the directory (and one level of subdirectories)
2. Identify the module's role:
   - What problem space does it own?
   - What are its key exports (public API)?
   - What are its internal implementation files?
   - What are its dependencies (imports from outside the module)?
   - What depends on it (search for imports of this module)?
3. Structure the README:

```markdown
# {Module Name}

{One-paragraph description of what this module does and why it exists.}

## Key Exports

| Export | Description |
|---|---|
| `{name}` | {what it does, when to use it} |

## Architecture

{Only include this section if the module has non-obvious internal structure.
Describe the key files and how they relate. Mention any patterns used
(state machine, pub/sub, pipeline, etc.).}

## Usage

{Code examples showing how to import and use the module's public API.
Use real import paths from the project.}

## Dependencies

{What this module depends on and why. Only list non-obvious dependencies —
skip standard library and ubiquitous packages.}
```

4. If a README already exists, update it rather than replacing it.
   Preserve any sections the existing README has that your analysis
   doesn't cover (e.g., "Known Issues", "Migration Guide").

#### API Reference Mode

For HTTP APIs (route files, API directories):

1. Read all route/endpoint definitions
2. For each endpoint, document:
   - **Method + Path**: `GET /api/users/:id`
   - **Description**: What it does
   - **Parameters**: Path params, query params, request body (with types)
   - **Response**: Success shape (with example), status codes
   - **Errors**: Error codes and their meanings
   - **Authentication**: Required auth level, if applicable
   - **Example**: curl or fetch example for non-trivial endpoints

For exported libraries:

1. Read all public exports
2. For each export, document:
   - **Name and type**: function, class, constant, type
   - **Description**: Purpose and usage context
   - **Parameters/Properties**: With types and semantics
   - **Return type**: With guarantees
   - **Example**: Import and usage

Structure as a single reference document with a table of contents.

### Phase 3: WRITE

1. Apply the detected style consistently
2. For function-level: insert doc comments directly above each function
3. For module-level: write or update README.md in the target directory
4. For API reference: write to a location that makes sense for the project
   (e.g., `docs/api/`, or adjacent to the route files)
5. Run typecheck after writing to ensure doc comments don't break anything
   (malformed JSDoc can cause TS errors)

### Phase 4: VERIFY

1. Re-read every doc comment you wrote
2. For each one, ask: "Does this tell the reader something they couldn't
   get from the signature alone?" If no, delete it.
3. Check for accuracy: does the doc match what the code actually does?
   Pay special attention to:
   - Parameter descriptions that don't match actual parameter names
   - Return type descriptions that don't match actual return types
   - Documented side effects that don't exist (or undocumented ones that do)
   - Examples that wouldn't actually compile/run

## Quality Gates

- **Information density**: Every doc comment must add information beyond the signature.
  "Returns the user ID" on `getUserId(): string` is a failure. Delete it.
- **Accuracy**: Docs must match actual code behavior. A wrong doc is worse than no doc.
- **Style consistency**: All generated docs must match the project's existing style.
  If the project uses `@returns` not `@return`, use `@returns`.
- **No boilerplate**: Never generate `@param name - The name` style filler.
  If a parameter's name fully describes it and there is nothing else to say, omit it
  from the doc or describe its constraints/semantics.
- **Typecheck clean**: Inserted doc comments must not break the build.
- **Trivial skip rate**: At least some functions should be skipped as trivial.
  If you documented every single function including obvious getters, you over-documented.

## Exit Protocol

Report what was documented:

```
=== Doc-Gen Report ===

Mode: {function-level | module-level | api-reference}
Target: {file or directory path}
Style: {detected style description}

Documented:
- {N} functions in {file} ({M} skipped as trivial)
  OR
- README.md written for {directory} ({N} exports, {M} sections)
  OR
- API reference: {N} endpoints documented

Skipped:
- {function/file}: {reason — trivial, already documented, etc.}
```

```
---HANDOFF---
- Generated {mode} docs for {target}
- Matched existing {style} convention
- {key decisions: what was skipped and why}
---
```