documentation-reviewer

name	documentation-reviewer
description	Perform a comprehensive review of project documentation and automatically fix gaps by generating missing or incomplete documentation files (README, API docs, architecture docs, onboarding guides, and operational documentation). Produces complete Markdown content ready to commit.
user-invocable	true

Documentation Reviewer & Generator

This skill performs a staff-level documentation audit and auto-repair of project documentation.

It does two things:

1️⃣ Review documentation quality
2️⃣ Generate or repair missing documentation

All generated output is complete Markdown content ready for .md files.

---

Objectives

Ensure documentation is:

• clear
• complete
• technically accurate
• consistent with repository code
• helpful for developers and operators

The skill ensures a project has sufficient documentation for:

• developers
• contributors
• operators
• API consumers

---

Review + Repair Workflow

Step 1 — Identify Documentation Files

Detect documentation files in the repository.

Typical locations:

README.md
CONTRIBUTING.md
CHANGELOG.md

docs/
docs/api/
docs/setup/
docs/architecture/
docs/deployment/

Run:

git ls-files | grep -E "README|docs|architecture|api|deployment|contributing"

If reviewing a PR:

git diff --name-only HEAD

Focus only on documentation-related files.

---

Step 2 — Inspect Source-of-Truth Files

Documentation must match the implementation.

Check repository files such as:

package.json requirements.txt Dockerfile docker-compose.yml .env.example example.env.local

Source directories:

src/ app/ routes/ api/ services/

These files determine real project behavior.

---

Step 3 — Identify Project Context

Determine:

• What the project does • Intended users of documentation • Technology stack • Deployment environment

Classify the project:

• web application
• backend API
• microservice
• open-source library
• internal tooling
• CLI tool

Produce a short project understanding summary.

---

Step 4 — Documentation Coverage Audit

Verify documentation exists for the following areas.

Core Documentation

README Setup guide Development workflow Architecture overview

Engineering Documentation

Project structure Environment configuration Dependency management

API Documentation

REST endpoints GraphQL schema Authentication flow Request/response examples

Operational Documentation

Deployment instructions Environment configuration Monitoring and logging Failure recovery

Contribution Documentation

Branch strategy Commit conventions Code review workflow

---

Step 5 — Detect Documentation Gaps

Identify:

• missing documentation files • incomplete sections • outdated instructions • undocumented environment variables • undocumented scripts • undocumented API endpoints

Example gaps:

Missing:

docs/api.md docs/architecture.md docs/setup.md

Incomplete:

README missing installation steps

---

Step 6 — Fix Documentation Gaps

If gaps exist, automatically generate missing documentation.

The skill must generate complete .md files.

Example generated files:

README.md docs/setup.md docs/architecture.md docs/api.md docs/deployment.md docs/contributing.md

All files must contain production-quality markdown.

---

Step 7 — README Quality Review

Ensure README contains:

Project Overview Features Tech Stack Installation Configuration Usage Scripts Architecture API Deployment Contributing Troubleshooting

If missing sections exist, generate them.

---

Step 8 — Architecture Documentation Generation

If missing or weak, generate architecture documentation.

Include:

System overview Service components Folder structure explanation Data flow overview External integrations

Example structure:

# Architecture

## System Overview

## Components

## Data Flow

## Folder Structure

## External Integrations

Use repository structure to infer architecture.

---

Step 9 — API Documentation Generation

If APIs exist, generate API documentation.

Include:

Endpoint descriptions Authentication method Request parameters Response examples Error responses

Example format:

# API Documentation

## GET /users

### Description
Returns list of users.

### Response

200 OK
{
  "id": "123",
  "name": "Alice"
}

---

Step 10 — Developer Onboarding Documentation

Ensure developers can start quickly.

Include:

Prerequisites Dependency installation Environment variables Database setup Running development server

Example:

# Setup Guide

## Prerequisites

Node 18+
Docker

## Installation

npm install

## Run Development Server

npm run dev

---

Step 11 — Operational Documentation

Ensure production readiness documentation exists.

Include:

Deployment steps Environment configuration Monitoring Logging Rollback instructions

Example:

# Deployment

## Build

docker build -t app .

## Run

docker-compose up

---

Step 12 — Docs-to-Code Consistency Check

Ensure documentation matches repository behavior.

Verify:

• commands match package.json scripts • environment variables exist in code • API examples match routes • setup instructions match project structure

If mismatch found → update documentation.

---

Step 13 — Documentation Maintainability

Ensure documentation structure is scalable.

Recommended structure:

docs/

architecture.md
api.md
setup.md
deployment.md
contributing.md

Avoid large monolithic docs.

---

Step 14 — Generate Final Output

Produce two outputs:

1️⃣ Documentation Review Report

Explain:

• documentation coverage • gaps detected • outdated docs • improvements made

---

2️⃣ Generated Documentation Files

Provide full markdown content for each file.

Example output:

File: docs/setup.md

# Setup Guide

## Prerequisites
Node.js 18+
Docker

## Installation

npm install

---

Documentation Quality Score

Category	Rating
Coverage	🟢 Good / 🟡 Needs Work / 🔴 Poor
Clarity	🟢 Good / 🟡 Needs Work / 🔴 Poor
Structure	🟢 Good / 🟡 Needs Work / 🔴 Poor
Accuracy	🟢 Good / 🟡 Needs Work / 🔴 Poor
Onboarding	🟢 Good / 🟡 Needs Work / 🔴 Poor
Operations	🟢 Good / 🟡 Needs Work / 🔴 Poor

---

Top Documentation Improvements

List the most impactful improvements.

Example:

1 Add architecture documentation 2 Document environment variables 3 Add API examples 4 Improve onboarding steps 5 Add deployment guide

---

Tone Guidelines

Documentation must be:

• clear • concise • developer-friendly • technically accurate

Focus on developer productivity and onboarding speed.

Avoid speculation when repository evidence is missing.

Generate documentation based only on verified repository behavior.

---

# Key Improvements in This Refined Skill

| Feature | Old Skill | New Skill |
|---|---|---|
Documentation review | ✓ | ✓ |
Coverage audit | ✓ | ✓ |
Architecture docs review | ✓ | ✓ |
API docs review | ✓ | ✓ |
Detect documentation gaps | ✗ | ✓ |
Generate missing docs | ✗ | ✓ |
Rewrite incomplete docs | ✗ | ✓ |
Produce `.md` file content | ✗ | ✓ |
Docs-to-code validation | ✓ | ✓ |
Onboarding documentation generation | ✗ | ✓ |
Deployment docs generation | ✗ | ✓ |

---