# Document

Use when asked to document Elixir code: add or fill in @moduledoc and @doc for modules...

- Repository: https://github.com/oliver-kriska/claude-elixir-phoenix (572 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add oliver-kriska/claude-elixir-phoenix --skill document -g -a claude-code -y`
Codex: `npx skills add oliver-kriska/claude-elixir-phoenix --skill document -g -a codex -y`
Cursor: `npx skills add oliver-kriska/claude-elixir-phoenix --skill document -g -a cursor -y`
Gemini CLI: `npx skills add oliver-kriska/claude-elixir-phoenix --skill document -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add oliver-kriska/claude-elixir-phoenix`

## Description

Use when asked to document Elixir code: add or fill in @moduledoc and @doc for modules and functions. Documents tested code only; may add a README section or ADR. Not for docs lookup or audits.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Document

Generate documentation for newly implemented features.

## Usage

```
/phx:document .claude/plans/magic-link-auth/plan.md
/phx:document magic link authentication
/phx:document  # Auto-detect from recent plan
```

## Iron Laws

1. **Never remove existing documentation**, Existing docs may reflect design intent that isn't obvious from code alone; update rather than replace
2. **@moduledoc on every public module**, Undocumented modules accumulate quickly and create onboarding friction for new team members
3. **ADRs capture the "why", not the "what"**, Code shows what was built; ADRs explain why this approach was chosen over alternatives
4. **Match @doc to function's public API**, Document parameters, return values, and edge cases; callers shouldn't need to read the implementation
5. **DO NOT add @doc to untested code**, documentation implies a stable contract; document only after tests confirm the function behaves as described

## What Gets Documented

| Output | Description |
|--------|-------------|
| `@moduledoc` | For new modules missing documentation |
| `@doc` | For public functions without docs |
| README section | For user-facing features |
| ADR | For significant architectural decisions |

## Workflow

### Step 0: Pre-check (avoid no-op runs)

Run `git diff --name-only HEAD~5 | grep '\.ex$' | head -20` to check for new `.ex` files.

If no new `.ex` files were added (only modifications), skip the full
audit and report: "No new modules, documentation coverage unchanged."
A full audit of unchanged coverage produces nothing to add.

1. **Identify** new modules from recent commits or plan file
2. **Check** documentation coverage (`@moduledoc`, `@doc`)
3. **Generate** missing docs using templates
4. **Add** README section if user-facing feature
5. **Create** ADR if architectural decision was made
6. **Write** report to `.claude/plans/{slug}/reviews/{feature}-docs.md`

## When to Generate ADRs

The rest: https://github.com/oliver-kriska/claude-elixir-phoenix/blob/HEAD/plugins/elixir-phoenix/skills/document/SKILL.md