review-docs

What this skill does

# Review Docs

Comprehensive documentation review, optimized for Docus/Nuxt Content but compatible with any Markdown documentation.

## Workflow Overview

This skill performs a 5-step review process:

1. **Detect Project Type** - Identify Docus/Nuxt Content vs generic Markdown
2. **Analyze Structure** - Map documentation organization, locales, sections
3. **Technical Validation** - Check frontmatter, MDC syntax (if applicable), file naming
4. **Content Quality Review** - Evaluate clarity, SEO, structure, i18n
5. **Generate Report** - Provide categorized, actionable recommendations

### Priority Levels

- **Critical** - Blocks deployment or causes errors (missing frontmatter, invalid MDC syntax)
- **Important** - Significantly impacts UX/SEO (poor metadata, passive voice, unclear headings)
- **Nice-to-have** - Polish and optimization suggestions (add callouts, improve examples)

### Expectations

This skill generates a **detailed report only**. After reviewing, it offers to fix identified issues if requested.

---

## Step 1: Detect Project Type

**Goal:** Determine if this is a Docus/Nuxt Content project or generic Markdown documentation.

### Detection Indicators

**Check for Docus/Nuxt Content:**
1. **package.json dependencies:**
   - `"docus"` - Docus theme
   - `"@nuxt/content"` - Nuxt Content module
   - `"@nuxtjs/mdc"` - MDC support

2. **Configuration files:**
   - `nuxt.config.ts` or `nuxt.config.js` with `@nuxt/content` module
   - `content.config.ts` - Content collections configuration

3. **Content structure:**
   - `content/` or `docs/content/` directory
   - `.navigation.yml` files in subdirectories
   - MDC syntax in markdown files (`::component-name`)

4. **Project structure:**
   - Numbered directories (`1.getting-started/`, `2.guide/`)
   - Frontmatter with `navigation`, `seo` fields

### Project Type Classification

**Type A: Docus/Nuxt Content Project**
- All Docus-specific validations apply
- MDC component syntax checks (u- prefix requirement)
- Nuxt Content frontmatter structure
- Navigation files (.navigation.yml)
- Full technical validation

**Type B: Generic Markdown Documentation**
- Basic Markdown validation only
- Generic frontmatter (title, description, date, author)
- Standard Markdown syntax
- Focus on content quality (SEO, clarity, structure)
- No Docus-specific technical checks

### Detection Output

After detection, note in the report:
```
Project Type: [Docus/Nuxt Content | Generic Markdown]
Validation Mode: [Full (Docus-specific) | Basic (Markdown-only)]
```

**Adapt validation steps based on detected type:**
- **Type A (Docus):** Execute all steps with full validation
- **Type B (Generic):** Skip Docus-specific checks, focus on content quality

---

## Step 2: Analyze Documentation Structure

### Locate Content Directory

Find the documentation content directory:
- Check for `docs/content/` (most common)
- Check for `content/` (root-level)
- Check for `app/content/` (alternative location)

### Detect Locales

Identify language structure by examining subdirectories:

**Single language** (no locale subdirectories):
```
content/
├── index.md
├── 1.getting-started/
└── 2.guide/
```

**Multi-language** (locale subdirectories):
```
content/
├── en/
│   ├── index.md
│   ├── 1.getting-started/
│   └── 2.guide/
└── fr/
    ├── index.md
    ├── 1.getting-started/
    └── 2.guide/
```

**Detection logic:**
- If immediate subdirectories are 2-letter codes (en, fr, es, de, etc.), it's multi-language
- If immediate subdirectories are numbered (1.getting-started), it's single language

### List Documentation Sections

Identify all numbered directories within each locale:
- `1.getting-started/`
- `2.guide/` or `2.concepts/`
- `3.api/` or `3.essentials/`
- `4.advanced/` or `4.ai/`

For each section, note:
- Section name
- Presence of `.navigation.yml` file
- Number of pages (count `.md` files)
- Page file names

### Verify Core Files

Check for required files:
- [ ] `index.md` exists at root of each locale
- [ ] `.navigation.yml` in each section directory
- [ ] Numbered files follow pattern (`1.introduction.md`, `2.installation.md`)

### Create Structure Map

Document the structure for the report:
```
Project: [project-name]
Locales: [en, fr] (or "Single language")
Sections:
  - 1.getting-started: 5 pages, .navigation.yml ✅
  - 2.guide: 8 pages, .navigation.yml ✅
  - 3.api: 3 pages, .navigation.yml ❌ (missing)
```

---

## Step 3: Technical Validation

**Adapt validation based on project type detected in Step 1.**

### For Docus/Nuxt Content Projects (Type A)

Perform full technical validation using [references/technical-checks.md](references/technical-checks.md):

**Validate:**
1. **Frontmatter structure** - Required: `title`, `description`. Optional: `navigation`, `seo`, `links`
2. **MDC component syntax** - All Nuxt UI components MUST have `u-` prefix (`::u-page-hero`, `:::u-button`)
3. **Code block labels** - All code blocks representing files need descriptive labels (` ```vue [App.vue] `, ` ```ts [config.ts] `)
4. **Code language consistency** - Code examples should match the project's language stack (e.g., TypeScript if the project uses TypeScript, `lang="ts"` on Vue `<script setup>`)
5. **Package manager coverage** - `::code-group` install blocks must cover all package managers the project/ecosystem supports
6. **Code preview** - Use `::code-preview` for visually renderable examples (tables, lists, rendered markdown, etc.)
7. **Code group scope** - Only group equivalent alternatives (e.g., package managers, framework variants) — don't mix unrelated steps (e.g., install command + config file)
8. **File naming** - Numbered directories/files, kebab-case, `.navigation.yml` in each section
9. **Hidden pages** - Use `navigation: false` for pages that should exist as routes but not appear in sidebar

**Common Critical Errors:**
- Missing `u-` prefix: `::page-hero` → should be `::u-page-hero`
- Missing required frontmatter: `title`, `description`
- Invalid `.navigation.yml` structure
- Missing section `index.md` causing 404 on section root URL

See [references/technical-checks.md](references/technical-checks.md) for complete validation rules, examples, and error patterns.

### For Generic Markdown Projects (Type B)

**Simplified validation** - Skip Docus-specific checks:

**Basic Frontmatter Validation:**
- Check for common fields: `title`, `description`, `date`, `author`, `tags`
- No strict requirements - just recommendations
- Flag if completely missing frontmatter

**Standard Markdown Syntax:**
- Validate basic markdown (headings, lists, links, code blocks)
- Check for broken internal links
- Verify image paths exist

**Skip:**
- MDC component syntax (not applicable)
- Nuxt Content frontmatter structure
- `.navigation.yml` files
- Docus-specific conventions

**Focus on:**
- Content quality (next step)
- SEO optimization
- Clarity and readability
- General structure

---

## Step 4: Content Quality Review

**This step applies to ALL project types** (both Docus and generic Markdown).

Evaluate content quality across four dimensions. Refer to reference files for detailed checklists.

### Clarity Review

Use [references/clarity-checks.md](references/clarity-checks.md) to check:
- **Voice & Tone:** Active voice, present tense, second person
- **Sentence Structure:** 15-20 words target, avoid wordy phrases
- **Paragraph Structure:** 2-5 sentences, 200-400 words between headings
- **Action-Based Headings:** Page titles (H1) and headings (H2/H3) use action verbs for guides (Nuxt pattern)
  - Examples: "Create Your First Module", "Configure your app", "Build a Plugin"
  - Exceptions: Getting Started (nouns), API (function names), Concepts (descriptive)
- **Terminology:** Consistent naming, technical terms defined
- **Code Examples:** Complete, copy-pasteable, realistic, with file labels

### SEO Review

Use [references/seo-checks.md](references/seo-checks.md) to check:
- **Titles:** 50-60 chars, keywords, unique
- **Descriptions:** 120