# Docs Find Documentation Gaps

> Find and report undocumented areas of a ZIO library project that need documentation coverage in the docs directory. Generates a TODO-style report.

- Skill: `zio/docs-find-documentation-gaps` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zio/docs-find-documentation-gaps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zio/docs-find-documentation-gaps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zio (https://skillmd.com/u/zio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zio/docs-find-documentation-gaps

---


# Finding Undocumented Areas

Scan the project to identify documentation gaps — public types, modules, and packages that lack coverage in the `docs/` directory. Produce a comprehensive report saved to `docs/undocumented-report.md`.

## Scope

$ARGUMENTS

If a specific module name is given (e.g., `schema`, `chunk`, `scope`), focus the analysis and recommendations on that module. Otherwise, scan the entire project.

## Step 1: Run the Scanner Script

Run the automated scanner to produce raw coverage data:

```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/docs-find-documentation-gaps/scan-undocumented.sh \
  > docs/undocumented-report.md
```

Pass an optional project root to scan a sub-module: `scan-undocumented.sh <path>`. Run with `--help` for the full usage.

**Exit codes:**

| Code | Meaning                                                                |
|------|------------------------------------------------------------------------|
| `0`  | Scan completed; report written to stdout. Inspect the report to see whether undocumented types were found — the exit code does not reflect coverage. |
| `2`  | Invocation error (extra arguments, project root not found, missing `docs/` directory). |

## Step 2: Enrich the Report with Manual Analysis

The bash script provides a mechanical scan. Now add intelligence by doing the following:

### 2a. Review the undocumented types

For each undocumented type flagged by the script:

1. **Read the source file** to understand what the type does.
2. **Classify its documentation priority**:
   - **Critical**: Core public API types that users interact with directly (e.g., `Schema`, `Codec`, `Chunk`). These need dedicated reference pages.
   - **High**: Important supporting types that appear in public API signatures (e.g., `Validation`, `Modifier`, `DynamicValue`). These need at least a section in a related page.
   - **Medium**: Internal-but-visible types that advanced users may encounter (e.g., `Deriver`, `ReflectTransformer`). These need brief mention.
   - **Low**: Truly internal types, platform-specific implementations, or test helpers. These can be skipped.
3. **Update the priority** in the report — move types into the correct priority section.

### 2b. Check documentation depth

For types that DO have documentation pages, check whether the coverage is adequate:

1. Read the existing doc page.
2. Read the source file for the type.
3. Look for:
   - **Missing methods**: Public methods on the type or companion that are not documented.
   - **Missing examples**: Types documented with prose but no code examples.
   - **Outdated signatures**: Method signatures in docs that don't match current source.
   - **Missing cross-references**: Related types that should link to each other but don't.

Add a "Documentation Depth" section to the report with these findings.

### 2c. Identify conceptual gaps

Beyond type-level coverage, look for missing conceptual documentation:

1. **Getting started guide**: Is there a quick-start for new users?
2. **Migration guides**: Any version migration docs needed?
3. **How-to guides**: Common tasks that need step-by-step guides.
4. **Architecture overview**: High-level design docs for contributors.

Add these as a separate "Conceptual Gaps" section.

## Step 3: Write the Final Report

Write the final report to `docs/undocumented-report.md` with this structure:

```markdown
---
id: undocumented-report
title: "Documentation Coverage Report"
---

# Documentation Coverage Report

## Summary
[Coverage statistics table from script]

## Critical: Missing Reference Pages
[Types that need dedicated doc pages, with brief description of each]

## High Priority: Incomplete Coverage
[Types with pages that need expansion, or important types without pages]

## Medium Priority: Brief Mentions Needed
[Types that should be mentioned in related pages]

## Documentation Depth Issues
[Existing pages that need updates — missing methods, examples, etc.]

## Conceptual Gaps
[Missing guides, overviews, tutorials]

## Low Priority / Skip
[Internal types that don't need documentation, with brief justification]

## Suggested Actions
[Ordered TODO checklist of documentation tasks]
```

### Report Guidelines

- Use `- [ ]` checkbox syntax for actionable items so they serve as a TODO list.
- Include source file paths so a documentation writer can quickly find the code.
- For each suggested action, estimate scope: "new page", "new section", "brief mention", or "update existing".
- Group suggestions by module for easy assignment.

## Step 4: Update Index

Do NOT add the report to `docs/index.md` — it is an internal tracking document, not user-facing documentation.