review-user-guide

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:

1. Repository info gathered
2. Product type detected
3. Deep analysis (relevant sub-phases per product type)
4. Existing user-guide validated (if present)
5. Report generated
6. 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.

Forms — Rails: grep -rl "form_for\|form_with\|form_tag" app/views/. Django: find . -name "forms.py". React/Vue: grep -rl "<form\|<Form\|useForm\|formik\|react-hook-form" --include="*.tsx" --include="*.jsx".

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:

1. H1 title must be exactly # User Guide (not # Manual).

2. Required H2 sections (per product type) present in correct order.

3. TOC links resolve to actual sections.

4. 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.

5. 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

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