Review User Guide Documentation Skill

Review User Guide Documentation

Review or create docs/user-guide.md from an end-user perspective. Works for all project types and languages.

Phase Tracking

Use TaskCreate to track progress: one task per phase below. Mark in_progress when starting, completed when results are recorded. Do NOT include the task list in the final output — it's internal tracking.

Required phases:

Repository info gathered
Product type detected
Deep analysis (relevant sub-phases per product type)
Existing user-guide validated (if present)
Report generated
User guide written/updated (if approved)

Evidence rule: Every check must record (a) what the guide claims, (b) what the code shows, (c) MATCH / MISMATCH / MISSING. A bare "PASS" without code evidence is invalid.

User Guide Document Structure

Required H1 + H2 sections:

# User Guide

## Table of Contents
## Getting Started
## Features
## {Project-Type-Specific Sections}
## Configuration
## Troubleshooting
## FAQ

Project-Type-Specific Sections

| Type | Required H2 sections | | ---- | -------------------- | | Web App | Navigation, Pages, Step-by-Step Guides, Workflows | | CLI Tool | Commands, Options & Flags, Examples | | REST API | Authentication, Endpoints, Request/Response Examples, Error Handling | | Library / SDK | Installation, Quick Start, API Reference, Examples | | Mobile App | Screens, Navigation, Features, Offline Mode | | Desktop App | Windows & Views, Menus & Toolbars, Keyboard Shortcuts, Features |

MCP Tools with Fallbacks

Prefer MCP tools when available; fall back to CLI on errors. Don't let MCP failures block the review.

| Operation | Preferred | Fallback | | --- | --- | --- | | Get file contents | mcp__github__get_file_contents | cat <file> | | Repo metadata | gh repo view --json owner,name,description | n/a | | Library docs | mcp__context7__* | WebSearch → mcp__fetch__fetch |

Phase 1: Repository Info

gh repo view --json owner,name,description
ls -la docs/user-guide.md docs/manual.md 2>/dev/null

Record: organization, repository, description, has_user_guide. If docs/manual.md exists but docs/user-guide.md does not, plan to rename.

Phase 2: Detect Product Type

Classify as one of: web_app, cli_tool, api, library, mobile_app, desktop_app, hybrid.

Detection signals (use the appropriate one — don't run all):

Rails — Gemfile containing rails; config/routes.rb; app/controllers/, app/views/
Django — manage.py; */urls.py; requirements.txt/pyproject.toml containing django
Express / Next.js / React — package.json with express/koa/fastify/nest/next/react/vue/angular/svelte; pages/, app/, src/pages/, src/app/
Laravel — artisan, routes/web.php, app/Http/Controllers/
CLI tool — package.json with bin; usage of argparse/click/typer/commander/yargs/clap/cobra; cmd/ or cli/ directory
REST API — route decorators (@app.route, @router, @RestController, router.get); api/ or routes/; FastAPI/Flask/Express/Gin/Echo/Fiber
Library / SDK — package.json main/exports; setup.py / pyproject.toml with name/packages; no app entry point
Mobile — android/, ios/, pubspec.yaml, lib/main.dart; package.json with react-native/expo/ionic/capacitor
Hybrid — multiple types match (e.g. CLI exposing both a binary and a library)

Phase 3: Deep Analysis

Run only the sub-phases that match the detected product type. For each, record exact counts and file:line locations as evidence.

3.1 Web Applications

Routes / pages — Rails: cat config/routes.rb, list app/controllers/. Django: cat */urls.py, find views.py. Express: grep -rn "router\.\(get\|post\|put\|delete\|patch\)" --include="*.js" --include="*.ts". Next.js / React: list pages/, app/, src/pages/, src/app/ for *.tsx/*.jsx.

Models / data — Rails: app/models/, db/schema.rb. Django: find . -name "models.py". Generic: any Schema/type Entity declarations.

Help text & UI guidance (CRITICAL — reuse in the guide): look for help_text:, placeholder:, helperText, tooltip, hint, description:, aria-describedby, list_items: across views/components. This text is what users see on screen and must be reproduced verbatim in the Step-by-Step Guides.

Conditional field visibility (CRITICAL): find fields that show/hide based on other fields.

Rails (Stimulus / inline JS): wrapper_class.*hide-, wrapper_class.*show-, data-action.*toggle, style.display, .classList.toggle.
React/Vue: v-if=, v-show=, x-show=, {cond && <, hidden={.
For each conditional field, record: trigger field, trigger condition (value/state), affected fields, and visibility logic (show-when-true vs hide-when-true).

Form section structure — form_section, <fieldset>, <legend>, <FormSection>, <FormGroup>, fieldsets (Django admin). Record section title and description text.

UI components, navigation — component files; nav, menu, sidebar, header, footer, navbar, drawer patterns.

3.2 CLI Tools

Commands — Python (Click/Typer/argparse): @click.command, @app.command, add_parser, add_subparser. Node (Commander/Yargs): .command(, .option(, yargs.. Go (Cobra): cobra.Command, cmd.AddCommand. Rust (Clap): #[command, Command::new.

Help output — Try ./bin/* --help if executable. Otherwise extract from source.

Options / flags — add_argument, .option(, .flag(, --<name> patterns.

3.3 REST APIs

Endpoints — FastAPI/Flask: @app.<method>, @router.<method>. Express: router.<method>, app.<method>. Rails API: app/controllers/api/, namespace blocks in config/routes.rb.

Schemas — Schema, Serializer, DTO, interface .*Request, type .*Response.

Authentication — search for auth, jwt, bearer, api.key, oauth, token. Identify the actual mechanism used.

OpenAPI / Swagger — openapi.yaml, openapi.json, swagger.*, api-spec.*.

3.4 Libraries / SDKs

Public API — Python: __all__, __init__.py exports, top-level class/def. Node/TS: export statements. Rust: pub fn/pub struct/pub enum/pub trait. Go: capitalized func/type.

Docstrings — comments preceding public items ("""…""", ///, //).

Examples — examples/, example/, demo/, files matching *example* / *demo*.

3.5 Mobile Apps

Screens — Flutter: lib/**/*screen*.dart, *page*.dart, files using Scaffold, MaterialApp. React Native: *Screen* files, files using createStackNavigator, createBottomTabNavigator.

Navigation — Navigator, createNavigator, route definitions.

Phase 4: Validate Existing User Guide

If docs/user-guide.md exists:

H1 title must be exactly # User Guide (not # Manual).
Required H2 sections (per product type) present in correct order.
TOC links resolve to actual sections.
Cross-reference table (MANDATORY):

| Documented Feature | Code Evidence | | ------------------ | ------------- | | {claim from guide} | {file:function, or MISSING} |

For each documented feature: confirm it exists, confirm description matches implementation, flag outdated examples. For each feature found in Phase 3: confirm it's documented, otherwise flag undocumented.
Web-app specific (if applicable):
- Forms documented as guided walkthroughs, not field tables.
- Help text in the guide matches the actual help_text: / helperText in form views.
- Conditional visibility is explicitly documented (which fields appear/disappear and when).
- Form section structure in the guide matches the UI layout.

If docs/manual.md exists, plan to rename to docs/user-guide.md and replace the H1 title.

Phase 5: Generate Report

Pre-report verification: every applicable phase task is marked complete; cross-reference evidence is recorded; counts are exact (not "some" / "a few").

## User Guide Review Report

### Repository Info
- Organization: {org}
- Repository: {repo}
- Product Type: {type}
- Document Status: {exists / missing}

### Structure Checks
- H1 title `# User Guide`: {PASS / FAIL}
- Required H2 sections: {PASS / FAIL — list missing}
- TOC links valid: {PASS / FAIL}

### Content Accuracy
- Getting Started matches actual setup: {PASS / FAIL}
- All features documented: {PASS / FAIL}
- {Product-type-specific checks}

### Web App Style Checks (if applicable)
- Forms as guided walkthroughs: {PASS / FAIL}
- Help text reused from UI code: {PASS / FAIL}
- Conditional visibility documented: {PASS / FAIL}
- Section structure matches UI: {PASS / FAIL}

### Coverage
- Documented features: {n}
- Features in code: {n}
- Undocumented features: {list with file:line}
- Documented but removed: {list}
- Conditional fields documented: {n} of {total}
- Help texts incorporated: {n} of {total}

### Proposed Changes
{Specific edits with file:line targets}

Phase 6: Write or Update the Guide

After the report is approved, write docs/user-guide.md using the structure below. Do not paste templates verbatim — fill them with content discovered in Phase 3.

Required structure (all product types)

# User Guide

## Table of Contents

- [Getting Started](#getting-started)
- [Features](#features)
- {Product-type-specific sections}
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)

## Getting Started

### Prerequisites / Requirements
{Detected from package files, README, deployment configs}

### Installation / Access
{Install command, URL, or onboarding step}

### First-Time Setup / Quick Start
{Minimal example or numbered steps}

## Features

### Feature Overview

| Feature | Description | Location |
| ------- | ----------- | -------- |
| {name}  | {description} | {page/command/endpoint} |

Product-type-specific guidance

Web Apps — Pages section. For each page: URL, purpose (inferred from controller/view), what the user sees on landing, then a "What You Can Do Here" subsection listing each action with what it does and prerequisites. If a page has a status workflow, document the lifecycle.

Web Apps — Step-by-Step Guides (CRITICAL formatting rule). This section MUST be a guided walkthrough, NOT a field table. For each form:

Open with: "Navigate to {page} in the sidebar and click {button label}."
For each form section discovered in Phase 3: include the section's description text from the UI; if list_items explain enum options, reproduce them as a bulleted guide.
For each field in the section, use numbered steps:
1. {Field Label} — {use the actual help_text from the UI verbatim if present; otherwise plain-language explanation}.
  - For dropdowns/enums, list each option with its description (use list_items text from UI).
For trigger fields with conditional visibility, document inline:
When you check this box / select "{value}", the following fields appear:
- {Conditional Field} — {help text}
For inverse visibility:

When you check this box, the {section name} fields below are no longer needed and will be hidden.
Close with "Saving and Next Steps": where the user is redirected, the starting status, and what to do next.

Web Apps — Workflows. For each major end-to-end flow: goal, then numbered steps with Navigate to, Action, Expected result.

CLI Tools — Commands. For each command: description, usage line (command [options] <args>), arguments table (Argument | Required | Description), one example. Then global Options & Flags table, then per-command flags.

CLI Tools — Examples. Basic Usage → Common Workflows (multi-step) → Advanced Usage (complex options).

REST APIs — Authentication. Method (API Key / OAuth / JWT), how to obtain credentials, header example, query-parameter example.

REST APIs — Endpoints. For each: METHOD, path, parameters table (Name | In | Type | Required | Description), example request body (JSON), example response (JSON), status codes table.

REST APIs — Error Handling. Error response format, error codes table (Code | HTTP Status | Description | Resolution).

Libraries — Quick Start. One minimal working example in the project's primary language.

Libraries — API Reference. For each public class/function: description from docstring, signature in a fenced block, parameters table, return type, one usage example.

Mobile Apps — Screens. For each screen: name, navigation entry point, primary actions, what the user sees, screen-specific gestures or shortcuts.

Configuration, Troubleshooting, FAQ (all types)

Configuration — settings table (Setting | Description | Default), environment variables table.
Troubleshooting — Common Issues (Symptom / Cause / Solution), Error Messages table.
FAQ — questions grounded in real user scenarios from issue templates, support patterns, or Phase 3 findings. Don't invent generic Q&As.

Phase 7: Run Linters

After writing/updating the guide, run /co-dev:run-linters and fix any errors before reporting completion.

Validation Checklist

Before completing, confirm:

[ ] H1 is exactly # User Guide
[ ] All required H2 sections present in correct order
[ ] TOC links resolve
[ ] Getting Started actually gets users started
[ ] All user-facing features documented; nothing fabricated
[ ] Examples tested against actual code
[ ] Configuration matches code
[ ] Step-by-Step Guides use walkthrough style (not field tables)
[ ] UI help text incorporated verbatim
[ ] Conditional field visibility documented with callout blocks

Important Rules

Write for end-users. Assume no code knowledge. Explain technical terms.
Never fabricate features. Only document what exists in code.
Cross-reference always. Every documented feature must have a code-evidence pair.
Examples must work with actual code — test them.
Document the happy path first, then edge cases.
Ask before modifying. Show proposed changes and get approval.
Preserve existing valid content — only update or add, don't strip.
Walkthrough style, not field tables — for web app forms (rule 14 is non-negotiable).
Reuse UI help text verbatim — extract from help_text:, helperText, placeholder:, list_items: in the actual code.
Document conditional visibility with explicit callouts ("When you check this box, the following fields appear").
Run linters after changes — always.
Never validate against world knowledge alone. Don't fact-check version numbers or external claims from training data — use web search or repo files.
Complete all phases — skipping reveals nothing; cross-referencing reveals everything.

Agent Skills: Review User Guide Documentation

Install this agent skill to your local

Skill Files