skills.rest
rob-broadley
rob-broadleyCOMMUNITY
Explore all skills by this author →
GitHub

docs-review

Review documentation accuracy and completeness against exported symbols and key files.

Updated May 10, 2026
Search Tags:#code review#documentation#onboarding#API contracts#docstrings#stale docs#severity model
One-click install
npx skills add https://github.com/rob-broadley/ai-airbase --skill docs-review-rob-broadley
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-review
Source: https://github.com/rob-broadley/ai-airbase/tree/main/cadre/skills/docs-review
Command: npx skills add https://github.com/rob-broadley/ai-airbase --skill docs-review-rob-broadley

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you verify that documentation stays accurate and complete when code changes, preventing readers from being misled by outdated comments, broken examples, or missing required docs.

Core Features & Use Cases

  • Coverage thresholds: Enforces documentation requirements for exported symbols and key project docs like README and DEVELOPMENT.md.
  • Docstring usefulness rubric: Distinguishes missing, tautological, partial, and high-value documentation to focus review effort on meaningful improvements.
  • Onboarding simulation: Checks whether a new engineer can answer the essential “how/what/who” questions using the existing documentation.
  • Accuracy signals & decay detection: Flags documentation that describes old behavior, mismatched parameters/returns, broken examples, stale links, and architecture/decision drift.
  • Completeness checklist: Ensures doc comments include what the API does, preconditions, postconditions, error conditions, and non-obvious behavior.

Quick Start

Ask the AI to review the documentation changes in your branch against exported APIs and README/DEVELOPMENT.md coverage expectations for completeness, accuracy, and onboarding usefulness.

Frequently Asked Questions about docs-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I catch stale or missing documentation before merging code changes?▼

To catch stale or missing documentation before merge, run automated documentation review checks across exported symbols and key files. This validates docstring presence, detects outdated statements, and enforces severity-based coverage thresholds on pull requests modifying public APIs.

What is a docstring usefulness rubric for code review?▼

A docstring usefulness rubric for code review distinguishes missing, tautological, partial, and high-value documentation. It focuses review effort on meaningful improvements by evaluating whether doc comments explain what an API does, preconditions, postconditions, and error conditions.

How do I check if my README and DEVELOPMENT.md files are sufficient for onboarding?▼

Checking README and DEVELOPMENT.md onboarding sufficiency involves simulating a new engineer's experience. Review documentation to verify they can answer essential how, what, and who questions using completeness checklists and accuracy signals for behavior drift.

Can I enforce documentation coverage thresholds for exported symbols on pull requests?▼

You can enforce documentation coverage thresholds for exported symbols on pull requests. The review process validates doc comment presence and usefulness, ensuring comments include API behavior, preconditions, postconditions, error conditions, and non-obvious behavior before merge.

What is the best way to detect outdated API contracts and broken examples in documentation?▼

The best way to detect outdated API contracts and broken examples is evaluating accuracy signals and decay detection. This flags documentation describing old behavior, mismatched parameters or returns, broken examples, stale links, and architecture or decision drift.

When should I not use automated documentation review checks?▼

Automated documentation review checks should not be used when pull requests do not modify public APIs, update behavior, or touch README and DEVELOPMENT.md content. The severity-based review standard applies specifically to exported symbols and key developer-facing files.

Related Skills

Explore More Software Engineering Skills→
arloliuarloliu
3

go-api-review

Review a Go package's exported API and README for developer experience.

Community
Intermediate
ToqsickToqsick

github-pr-merge-readiness

Assess GitHub Pull Request merge readiness via CI status, scope, and conflicts.

Community
Advanced
xxihxxih
1

springboot-verification

Validate Spring Boot applications with build, static analysis, coverage, and security scans.

Community
Advanced
spencerbeggsspencerbeggs

docs-review-package

Validate package.json metadata, dependency ranges, and peer dependency compatibility.

Community
Intermediate