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.
git clone --depth 1 https://github.com/existential-birds/beagle /tmp/elixir-docs-review && cp -r /tmp/elixir-docs-review/plugins/beagle-elixir/skills/elixir-docs-review ~/.claude/skills/elixir-docs-reviewSKILL.md
# Elixir Documentation Review ## Quick Reference | Issue Type | Reference | |------------|-----------| | @moduledoc, @doc quality, anti-patterns | [references/doc-quality.md](references/doc-quality.md) | | @spec, @type, @typedoc coverage | [references/spec-coverage.md](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 | ## Gates (sequenced — do not skip) Work in order. **Do not draft or ship a finding until the prior step passes.** 1. **Scope lock** — **Pass when:** You listed the exact `.ex`/`.exs` file paths (or `Module` names) under review; no vague “the project” scope. 2. **Full-context read** — **Pass when:** For each candidate issue, you read the full surrounding definition (all clauses for multi-clause functions; full `@moduledoc` block for module-level claims), not only a diff hunk or search snippet. 3. **Evidence bundle** — **Pass when:** Every draft finding uses the `[FILE:LINE] ISSUE_TITLE` header (line range allowed) **and** includes a verbatim quote or pointer to the `@doc` / `@spec` / doctest text in question. `Module.function/arity` may appear as supporting context but does not replace the `[FILE:LINE]` anchor. For “doctest fails” claims, **Pass when:** you cite `mix test` output for the relevant file or line, or the exact error string. 4. **Protocol before report** — **Pass when:** You loaded and followed [review-verification-protocol](../review-verification-protocol/SKILL.md) (its Pre-Report checklist) **before** finalizing the issue list—not after. ## When to Load References - Reviewing @moduledoc or @doc quality, seeing anti-patterns -> doc-quality.md - Reviewing @spec, @type, or @typedoc coverage -> spec-coverage.md
tag and push a release after the release PR is merged
create a release PR (auto-detects previous tag)
Guides architectural decisions for Deep Agents applications. Use when deciding between Deep Agents vs alternatives, choosing backend strategies, designing subagent systems, or selecting middleware approaches.
Reviews Deep Agents code for bugs, anti-patterns, and improvements. Use when reviewing code that uses create_deep_agent, backends, subagents, middleware, or human-in-the-loop patterns. Catches common configuration and usage mistakes.
Implements agents using Deep Agents. Use when building agents with create_deep_agent, configuring backends, defining subagents, adding middleware, or setting up human-in-the-loop workflows.
Guides architectural decisions for LangGraph applications. Use when deciding between LangGraph vs alternatives, choosing state management strategies, designing multi-agent systems, or selecting persistence and streaming approaches.
Reviews LangGraph code for bugs, anti-patterns, and improvements. Use when reviewing code that uses StateGraph, nodes, edges, checkpointing, or other LangGraph features. Catches common mistakes in state management, graph structure, and async patterns.
Implements stateful agent graphs using LangGraph. Use when building graphs, adding nodes/edges, defining state schemas, implementing checkpointing, handling interrupts, or creating multi-agent systems with LangGraph.