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

• Never remove existing documentation — Existing docs may reflect design intent that isn't obvious from code alone; update rather than replace

• @moduledoc on every public module — Undocumented modules accumulate quickly and create onboarding friction for new team members

• ADRs capture the "why", not the "what" — Code shows what was built; ADRs explain why this approach was chosen over alternatives

• Match @doc to function's public API — Document parameters, return values, and edge cases; callers shouldn't need to read the implementation

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

• Identify new modules from recent commits or plan file

• Check documentation coverage (@moduledoc , @doc )

• Generate missing docs using templates

• Add README section if user-facing feature

• Create ADR if architectural decision was made

• Write report to .claude/plans/{slug}/reviews/{feature}-docs.md

When to Generate ADRs

Trigger Create ADR

New external dependency Yes

New database table Maybe (if schema non-obvious)

New OTP process Yes (explain why process needed)

New context Maybe (if boundaries non-obvious)

New auth mechanism Yes

Performance optimization Yes

Integration with Workflow

/phx:plan → /phx:work → /phx:review ↓ /phx:document ← YOU ARE HERE (optional, suggested after review passes)

References

• references/doc-templates.md — @moduledoc, @doc, README, ADR templates

• references/output-format.md — Documentation report format

• references/doc-best-practices.md — Elixir documentation best practices

• references/documentation-patterns.md — Detailed documentation patterns