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