ReddRadar
Agent skill
elixir-docs-review
Reviews Elixir documentation for completeness, quality, and ExDoc best practices. Use when auditing @moduledoc, @doc, @spec coverage, doctest correctness, and cross-reference usage in .ex files.
Install this agent skill to your Project
npx add-skill https://github.com/existential-birds/beagle/tree/main/plugins/beagle-elixir/skills/elixir-docs-review
SKILL.md
Elixir Documentation Review
Quick Reference
| Issue Type | Reference |
|---|---|
| @moduledoc, @doc quality, anti-patterns | references/doc-quality.md |
| @spec, @type, @typedoc coverage | references/spec-coverage.md |
Review Checklist
Module Documentation
- All public modules have @moduledoc
- First-line summary is concise (one line, used by tools as summary)
- @moduledoc includes ## Examples where appropriate
- @moduledoc false only on internal/implementation modules
Function Documentation
- All public functions have @doc
- All public functions have @spec
- @doc describes return values clearly
- Multi-clause functions documented before first clause
- Function head declared when arg names need clarification
Doctests
- Doctests present for pure, deterministic functions
- No doctests for side-effectful operations (DB, HTTP, etc.)
- Doctests actually run (module included in test file)
Cross-References
- Module references use backtick auto-linking (
MyModule) - Function refs use proper arity format (
function/2) - Type refs use t: prefix (
t:typename/0) - No plain-text references where auto-links are possible
Metadata
- @since annotations on new public API additions
- @deprecated with migration guidance where appropriate
Valid Patterns (Do NOT Flag)
- @doc false on callback implementations - Documented at behaviour level
- @doc false on protocol implementations - Protocol docs cover the intent
- Missing @spec on private functions - @spec optional for internals
- Short @moduledoc without ## Examples on simple utility modules - Not every module needs examples
- Using @impl true without separate @doc - Inherits documentation from behaviour
Context-Sensitive Rules
| Issue | Flag ONLY IF |
|---|---|
| Missing @moduledoc | Module is public AND not a protocol impl |
| Missing @spec | Function is public AND exported |
| Missing doctests | Function is pure AND deterministic |
| Generic @doc | Doc restates function name without adding value |
When to Load References
- Reviewing @moduledoc or @doc quality, seeing anti-patterns -> doc-quality.md
- Reviewing @spec, @type, or @typedoc coverage -> spec-coverage.md
Before Submitting Findings
Load and follow review-verification-protocol before reporting any issue.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
existential-birds/beagle
review-python
Comprehensive Python/FastAPI backend code review with optional parallel agents
existential-birds/beagle
review-verification-protocol
Mandatory verification steps for all code reviews to reduce false positives. Load this skill before reporting ANY code review findings.
existential-birds/beagle
sqlalchemy-code-review
Reviews SQLAlchemy code for session management, relationships, N+1 queries, and migration patterns. Use when reviewing SQLAlchemy 2.0 code, checking session lifecycle, relationship() usage, or Alembic migrations.
existential-birds/beagle
fastapi-code-review
Reviews FastAPI code for routing patterns, dependency injection, validation, and async handlers. Use when reviewing FastAPI apps, checking APIRouter setup, Depends() usage, or response models.
existential-birds/beagle
pytest-code-review
Reviews pytest test code for async patterns, fixtures, parametrize, and mocking. Use when reviewing test_*.py files, checking async test functions, fixture usage, or mock patterns.
existential-birds/beagle
postgres-code-review
Reviews PostgreSQL code for indexing strategies, JSONB operations, connection pooling, and transaction safety. Use when reviewing SQL queries, database schemas, JSONB usage, or connection management.
Didn't find tool you were looking for?