oliver-kriska/claude-elixir-phoenix / targets/amp/skills/phx-document
phx-document
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
| references/doc-best-practices.md | markdown | 600 B |
| references/doc-templates.md | markdown | 1.1 KB |
| references/documentation-patterns.md | markdown | 6.9 KB |
| references/output-format.md | markdown | 803 B |
SKILL.md
View on GitHub---
name: phx-document
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.'
---
# 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
| 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
```text
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |