review-docs

Reviews Kotlin/Java KDoc, Javadoc, and Markdown changes against Spine documentation conventions.

2|Updated May 28, 2021

Search Tags:#markdown #documentation review #prose quality #javadoc #kdoc #link conventions #style linting

Ready to run

npx skills add https://github.com/SpineEventEngine/validation --skill review-docs-spineeventengine

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: review-docs
Source: https://github.com/SpineEventEngine/validation/tree/main/.agents/skills/review-docs
Command: npx skills add https://github.com/SpineEventEngine/validation --skill review-docs-spineeventengine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps prevent documentation regressions by reviewing Kotlin/Java KDoc, Javadoc, and Markdown changes against Spine documentation conventions.

Core Features & Use Cases

Checks KDoc/Javadoc quality for modified public or internal APIs, ensuring required documentation content and correct formatting.
Validates Markdown conventions across README and docs, including link style, heading hierarchy, code block formatting, and typographic quotes.
Applies Spine-specific prose quality rules to avoid widows, runts, orphans, and rivers, and keeps terminology consistent with code identifiers.

Quick Start

Ask the skill to review the documentation changes in your diff (Markdown under README and docs, plus KDoc/Javadoc in Kotlin/Java sources) before opening a doc-affecting PR.

Frequently Asked Questions about review-docs

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

FAQPage Schema

How do I review Kotlin KDoc and Markdown documentation changes before a PR?▼

Review documentation changes by scoping to only modified files, validating KDoc, Javadoc, and Markdown formatting, and producing a findings list separating Must fix, Should fix, and Nits with rewrite suggestions.

What documentation conventions are checked for Kotlin and Java source comments?▼

KDoc and Javadoc checks validate required documentation content, correct formatting, and prose quality rules for modified public or internal APIs to prevent documentation regressions.

How do I validate Markdown link style and heading hierarchy in README and docs files?▼

Validate Markdown conventions by checking link style, heading hierarchy, code block formatting, and typographic quotes across README and docs files included in the diff.

Can I check for prose quality issues like widows, orphans, and rivers in documentation?▼

Prose quality checks apply rules to avoid widows, runts, orphans, and rivers while keeping terminology consistent with code identifiers in both source comments and Markdown files.

Does documentation review require running a build or compiling the project?▼

Documentation review does not require running builds; it analyzes diffs touching source doc comments and Markdown files to produce a structured findings list without compilation.

What is the best way to lint documentation changes against Spine style conventions?▼

Lint documentation changes by applying Spine-specific conventions to KDoc, Javadoc, and Markdown diffs, generating file and line citations with rewrite suggestions categorized by severity.