# Docs Review

> Documentation review skill for assessing whether code changes are adequately reflected in documentation. Use this after /review to identify documentation gaps or outdated content. Use when this capability is needed.

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

---


# Documentation Review

Assess whether your code changes are adequately documented. This skill identifies features, configuration, CLI commands, and other user-facing changes that may need documentation updates.

## When to Use

Run `/docs-review` after completing `/review` and before committing, especially when your changes include:
- New features or functionality
- Changes to CLI commands or flags
- Configuration changes
- API modifications
- New entrypoints or user-facing behavior

## How to Review

Use the **Task tool** to spawn a sub-agent for documentation review. This provides a fresh perspective focused specifically on documentation accuracy.

### Step 1: Run the Sub-Agent Review

Use the Task tool with `subagent_type: "general-purpose"` and a prompt like:

```
Review all code changes (committed and uncommitted) between main and the current worktree for documentation impact. Run `git diff main` to see all changes.

Analyze the changes to identify:

1. **User-Facing Changes**: New or modified features, behaviors, or functionality that users interact with
2. **CLI/Entrypoint Changes**: New commands, flags, subcommands, or changes to existing ones
3. **Configuration Changes**: New config options, environment variables, or changes to existing settings
4. **API Changes**: New endpoints, changed request/response formats, or deprecations

For each identified change, check:
- Is there existing documentation that covers this? (README, docs/, inline help, etc.)
- Does the existing documentation accurately reflect the new behavior?
- Is the documentation discoverable where users would look for it?

Then examine any documentation changes in the diff:
- Do doc changes accurately describe the feature?
- Are there inconsistencies between code and docs?
- Is anything documented that doesn't match the implementation?

Report:
- **Gaps**: User-facing changes without adequate documentation
- **Outdated**: Existing docs that no longer match the code
- **Suggestions**: Specific documentation improvements (be concise, not exhaustive)
- **Assessment**: Overall documentation status (adequate / needs updates / critical gaps)

Be pragmatic: not every internal refactor needs docs. Focus on what users need to know.
```

### Step 2: Review the Report

The sub-agent will produce a documentation assessment. Review it and decide:

1. **Adequate**: Documentation is sufficient for the changes made. Proceed to commit.
2. **Needs Updates**: Minor gaps exist. Consider adding brief documentation before committing.
3. **Critical Gaps**: Major user-facing features are undocumented. Add documentation before proceeding.

### Step 3: Address Gaps (If Any)

If the review identifies gaps:

1. For CLI changes: Update help text, README usage sections, or man pages
2. For configuration: Update config documentation or example files
3. For features: Add or update relevant docs/ pages or README sections
4. For APIs: Update API documentation or OpenAPI specs

**Keep documentation honest and proportional** - the goal is accuracy, not comprehensiveness. A brief note is often better than verbose documentation that won't be maintained.

## Output

After completing the review process, summarize:
- What user-facing changes were identified
- Documentation status (adequate / gaps found)
- What documentation updates were made (if any)

**Note**: This review is advisory. Use judgment about what documentation is truly needed. Not every code change requires documentation updates.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/tessro) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->