review-documentation

Identifies gaps, inaccuracies, and drift in Go, protobuf, OpenAPI, and markdown documentation.

9|Updated Mar 22, 2026
One-click install
npx skills add https://github.com/paultyng/skill-issue --skill review-documentation-paultyng
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: review-documentation
Source: https://github.com/paultyng/skill-issue/tree/main/skills/review-documentation
Command: npx skills add https://github.com/paultyng/skill-issue --skill review-documentation-paultyng

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Documentation often falls out of sync with code, has missing comments, broken links, or incomplete guides that lead to developer confusion, wasted time, and bugs from outdated or incorrect information.

Core Features & Use Cases

  • Multi-format doc review: Checks Go doc comments, protobuf service/message comments, OpenAPI specs, and markdown files for completeness and accuracy.
  • Drift and gap detection: Identifies missing documentation, content that contradicts code implementation, drift between proto comments and OpenAPI descriptions, broken markdown links, and stale references.
  • Use Case: For a Go codebase with gRPC proto definitions and public API guides, run this skill before a release to catch missing package docs, mismatched OpenAPI endpoint descriptions, and broken README links.

Quick Start

Use the review-documentation skill to audit all documentation in the current codebase for accuracy and synchronization with the implementation.

Frequently Asked Questions about review-documentation

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

FAQPage Schema
How do I audit Go and protobuf documentation for accuracy and missing comments?

To audit Go and protobuf documentation, you can review exported APIs and service definitions to detect missing package docs, incomplete message comments, and content that contradicts code implementation across the codebase.

What is the best way to detect drift between OpenAPI specs and proto comments?

Detecting drift between OpenAPI specs and proto comments involves comparing service definitions and endpoint descriptions to identify mismatched content, stale references, and synchronization gaps within your technical documentation.

How do I check markdown files for broken links before a release?

Checking markdown files for broken links before a release involves scanning user-facing guides and README files to find stale references, missing documentation, and incomplete content that fails to match the codebase implementation.

Can I scope a documentation review to just a pull request?

Yes, you can scope a documentation review to a pull request to validate technical documentation completeness and accuracy, catching implementation drift and missing comments within the changed code paths.

Does this documentation review process require external dependencies?

No external dependencies are required to run the documentation review process, allowing you to directly audit multi-format documentation including Go, protobuf, OpenAPI, and markdown files for synchronization gaps.

Why does my technical documentation have missing API guides and mismatched descriptions?

Technical documentation often has missing API guides and mismatched descriptions due to implementation drift, where code changes outpace documentation updates, leading to broken links and incomplete service definitions.