---
description: Review documentation and code comments against standards
argument-hint: [glob-pattern] [--fix] [--diff] [--staged] [--strict] [--collapse]
allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Bash(task *)
---

# Documentation & Code Review for: $ARGUMENTS

## Phase 0: Parse Arguments and Determine Context

Extract from `$ARGUMENTS`:

- **Glob Pattern**: Optional (e.g., `docs/**/*.md`, `src/**/*.ts`)
- **--fix**: Apply auto-fixes where possible
- **--diff**: Review uncommitted changes
- **--staged**: Review staged changes (takes priority over --diff)
- **--strict**: Fail fast on first critical issue
- **--compare**: Compare against previous `.docs.report.local.md`
- **--collapse**: Apply collapsible section rules from agents.markdown.md (wraps long code blocks, step-by-step procedures, and long lists in `<details>/<summary>` tags)

### Context Determination (Priority Order)

**1. Staged changes (highest priority):**

````bash
git diff --cached --name-only --diff-filter=ACMR 2>/dev/null
```text

**2. Unstaged changes:**

```bash
git diff --name-only --diff-filter=ACMR 2>/dev/null
```text

**3. Glob pattern** (if provided in $ARGUMENTS)

**4. Default**: Current directory recursive

### Gitignore Filtering

**CRITICAL**: Never process gitignored files

```bash
# Filter out gitignored files
git check-ignore -v "$FILE" 2>/dev/null && skip
```text

**Always exclude:**

- Files matched by `.gitignore`
- `node_modules/`, `.git/`, `dist/`, `build/`, `.cache/`
- Binary files (`.png`, `.jpg`, `.pdf`, etc.)
- Lock files (`package-lock.json`, `bun.lockb`, etc.)

## Phase 1: Discover Standards and Tools

### 1.1 Locate Documentation Standards

Check for local [docs/guides/agents.markdown.md](../guides/agents.markdown.md):

```bash
cat docs/guides/agents.markdown.md
```

If not found, check for other repo-specific guides:

```bash
# Search for markdown guides, documentation, or standards files
find docs/ -type f \( -iname '*guide*.md' -o -iname '*standard*.md' -o -iname '*doc*.md' \) 2>/dev/null | head -5
```

If still not found, use shared standards:

```bash
cat ~/.claude/guides/agents.markdown.md
```

**If found:**

- Reference guide location in report
- Apply standards from guide
- Do NOT repeat guide content in report

**Standards apply to:**

- Markdown files: Use agents.markdown.md principles
- Code files: Use language-specific documentation standards

### 1.2 Detect Linting Tools

**Markdown linters:**

```bash
# Check for task commands
task --list 2>/dev/null | grep -E "lint|md:"

# Check for markdownlint
which markdownlint || npx --version > /dev/null
```text

**Code linters (detect by project):**

```bash
# TypeScript/JavaScript
test -f package.json && (grep -q "eslint" package.json || test -f .eslintrc*)

# Python
test -f pyproject.toml || test -f setup.py

# Kotlin
test -f build.gradle.kts || test -f pom.xml
```text

### 1.3 Detect Taskfile Linting

Check if project has Taskfile with scoped linting:

```bash
# Check for Taskfile
test -f Taskfile.yml || test -f Taskfile.yaml

# Check for lint task
task --list 2>/dev/null | grep "^  lint"

# Check if FILES variable supported (look for FILES in Taskfile)
grep -q '{{.FILES' Taskfile.yml 2>/dev/null
```text

**If Taskfile has `task lint` with FILES support:**

- Use `task lint FILES="file1.md,file2.ts"` for scoped linting
- More efficient than linting entire project
- Respects project-specific lint configuration

### 1.4 Collect Files for Review

Filter files by type:

**Markdown files** (`.md`, `.markdown`):

- Apply agents.markdown.md standards
- Run markdown linters

**TypeScript/JavaScript** (`.ts`, `.tsx`, `.js`, `.jsx`):

- Check TSDoc comments
- Validate function documentation

**Python** (`.py`):

- Check docstrings (Google/NumPy style)
- Validate module/class/function docs

**Kotlin** (`.kt`, `.kts`):

- Check KDoc comments
- Validate class/function documentation

**Skip:**

- Gitignored files
- Binary files
- Generated files (check for "auto-generated" header)
- Files > 10MB

## Phase 2: Review Documentation

### 2.1 Markdown Review

For each `.md` file:

**Lint with available tool:**

```bash
# Option 1: Taskfile with FILES support
task lint FILES="file1.md,file2.md"

# Option 2: markdownlint
npx markdownlint-cli2 "$FILE"

# Option 3: Manual validation
```text

**Apply agents.markdown.md standards:**

Reference [docs/guides/agents.markdown.md](../guides/agents.markdown.md) for:

- Emoji usage rules
- Checkbox list avoidance
- AI adjectives filter
- Audience awareness
- Collapsible sections usage

**Check for violations:**

- Emojis in headers
- Checkbox syntax `- [x]`, `- [ ]`
- AI adjectives (robust, comprehensive, seamless)
- Filler phrases ("helps you to", "allows you to")
- Undefined abbreviations
- Inconsistent terminology

**Link validation:**

```bash
# Extract links
grep -oP '\[.*?\]\(\K[^\)]+' "$FILE"

# Validate web links exist (check HTTP status)
curl -I --silent --fail "$URL" || echo "Broken link: $URL"
```text

**Auto-fix (if --fix):**

- Run markdown formatter
- Fix heading hierarchy
- Add missing language tags to code blocks

**Collapsible sections (if --collapse):**

Apply collapsible section rules from [agents.markdown.md](../guides/agents.markdown.md):

**Items to collapse in `<details>/<summary>` tags:**

1. **Code blocks with 10+ lines**
   - Count lines in fenced code blocks (```language)
   - Wrap in `<details><summary><strong>Example: [Description]</strong></summary>`
   - Preserve code block language tags

2. **Step-by-step procedures (numbered lists with 5+ items)**
   - Detect numbered lists starting with "1."
   - Wrap each major step in collapsible section
   - Summary format: `<summary><strong>Step N: [Action]</strong></summary>`

3. **Long lists (10+ items with descriptions)**
   - Count bullet/numbered list items
   - Wrap in collapsible with descriptive summary
   - Summary format: `<summary><strong>[List Topic]</strong></summary>`

4. **Troubleshooting sections**
   - Detect headers containing "Troubleshooting", "Error", "Issue", "Problem"
   - Wrap content in collapsible section
   - Summary format: `<summary><strong>Troubleshooting: [Issue Name]</strong></summary>`

5. **Optional/advanced configuration**
   - Detect headers with "Advanced", "Optional", "Reference"
   - Wrap content in collapsible section
   - Summary format: `<summary><strong>[Section Name]</strong></summary>`

**Items to keep visible (DO NOT collapse):**

1. Short lists (2-5 items)
2. Main narrative paragraphs
3. Simple definitions
4. Tables (any size)
5. Diagrams (mermaid, images, ASCII art)
6. Short code examples (< 10 lines)
7. Headers without content

**Summary text guidelines:**

- Use active, descriptive language
- Include what's inside: "Step 3: Run Integration Tests", "Example: AWS CLI Command"
- Avoid vague terms: "More info", "Click here", "Details"
- Use semantic HTML: `<strong>` for emphasis, `<code>` for commands

### 2.2 Code Documentation Review

#### File-Level Documentation (Top-Level Context)

**Purpose**: Provide high-level context for larger or business-critical files to explain background, purpose, and relationships.

**Placement**:
1. After copyright statements (if present)
2. Before import sections
3. At the very top of the file's logical content

**When to use**:
- Main infrastructure entrypoints (e.g., `sst.config.ts`, `main.tf`)
- Core business logic files (e.g., `payment-processor.ts`, `auth-handler.py`)
- Complex modules with multiple responsibilities
- Files that orchestrate other modules
- Configuration files with non-obvious structure

**TypeScript/JavaScript example:**

```typescript
/**
 * Copyright (c) 2024 Company Name
 */

/**
 * SST Configuration - Main Infrastructure Entrypoint
 *
 * This file is the main entrypoint for the SST infrastructure stack. It defines:
 * 1. Application configuration (name, stage settings, AWS provider)
 * 2. Infrastructure orchestration (import order for modules)
 * 3. Resource bindings (outputs available to application code via `Resource`)
 *
 * SST uses Pulumi under the hood for infrastructure as code. This file orchestrates
 * the deployment by importing infrastructure modules in the correct dependency order.
 *
 * @see {@link https://sst.dev/docs/} - SST Documentation
 * @see {@link https://www.pulumi.com/docs/clouds/aws/} - Pulumi AWS Provider
 * @see {@link ./infrastructure/database.ts} - Database infrastructure module
 */

import { Resource } from "sst";
// ... rest of imports
```

**Python example:**

```python
# Copyright (c) 2024 Company Name

"""Payment Processing Service - Stripe Integration

This module handles all payment processing operations using the Stripe API. It provides:
1. Payment intent creation and confirmation
2. Webhook event handling for async payment updates
3. Refund and cancellation operations
4. Payment method management

The service integrates with our internal billing system and maintains idempotency
for all payment operations to prevent duplicate charges.

See Also:
    https://stripe.com/docs/api - Stripe API Documentation
    https://stripe.com/docs/webhooks - Webhook Event Reference
    ./billing/invoice_generator.py - Invoice generation module
"""

import stripe
from typing import Dict, Optional
# ... rest of imports
```

**Kotlin example:**

```kotlin
/*
 * Copyright (c) 2024 Company Name
 */

/**
 * Event Processing Pipeline - Kafka Consumer
 *
 * This file implements the main event processing pipeline for the application. It handles:
 * 1. Kafka message consumption from multiple topics
 * 2. Event deserialization and validation
 * 3. Routing events to appropriate handlers
 * 4. Error handling and dead letter queue management
 *
 * The pipeline uses a thread pool for parallel processing while maintaining ordering
 * guarantees for events with the same partition key.
 *
 * @see [Kafka Consumer Documentation](https://kafka.apache.org/documentation/#consumerapi)
 * @see [Internal Event Schema](./schema/EventSchema.kt)
 * @see [Handler Registry](./handlers/HandlerRegistry.kt)
 */

package com.company.events

import org.apache.kafka.clients.consumer.KafkaConsumer
// ... rest of imports
```

**File-level documentation should include**:

1. **High-level purpose** - What this file does in the system
2. **Key responsibilities** - Numbered list of main functions (3-5 items)
3. **Context and background** - How it fits into the architecture
4. **Related references** - Links to:
   - External documentation (libraries, services, RFCs)
   - Internal modules (relative imports)
   - Architecture diagrams or ADRs (Architecture Decision Records)

**Validation checks**:
- File-level comment exists for infrastructure/config files
- File-level comment exists for core business logic files
- Comment appears after copyright, before imports
- Includes at least one `@see` or `See Also` reference
- External links are valid and accessible
- Internal file references use relative paths

#### TypeScript/JavaScript - TSDoc

**Standard**: [TSDoc](https://tsdoc.org/)

Check function/class documentation:

```typescript
/**
 * Brief description of what the function does
 *
 * @param paramName - Description of parameter
 * @param anotherParam - Description with type context
 * @returns Description of return value
 * @throws {ErrorType} When error condition occurs
 *
 * @example
 * ```typescript
 * const result = myFunction('input');
 * ```
 *
 * @see https://example.com/api - Relevant external reference
 */
```text

**Required documentation:**

- All exported functions/classes
- All public methods
- Complex internal functions

**Focus on:**

- WHAT the function does (one-line summary)
- Parameter descriptions and types
- Return value description
- Error conditions

**Explain WHY only for:**

- Non-obvious implementation patterns
- Performance optimizations
- Workarounds for library/service limitations
- Business logic decisions

**External references:**

- Link to external library docs
- Link to AWS service docs
- Link to RFC or specification
- Validate all links are accessible

#### Python - Docstrings

**Standard**: Google or NumPy style

```python
def function_name(param1: str, param2: int) -> bool:
    """Brief description of what the function does.

    Longer description if needed to explain the function's purpose.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Description of return value

    Raises:
        ValueError: When invalid input provided
        TypeError: When wrong type passed

    Example:
        >>> result = function_name('test', 42)
        >>> print(result)
        True

    See Also:
        https://example.com/api - Relevant documentation
    """
```text

**Required:**

- Module-level docstrings
- Class docstrings
- Public function docstrings

**Check for:**

- Missing Args/Returns sections
- Undocumented exceptions
- Broken reference links

#### Kotlin - KDoc

**Standard**: [KDoc](https://kotlinlang.org/docs/kotlin-doc.html)

```kotlin
/**
 * Brief description of what the function does
 *
 * Longer description explaining the purpose and context.
 *
 * @param paramName Description of parameter
 * @param anotherParam Description with context
 * @return Description of return value
 * @throws IllegalArgumentException When invalid input
 *
 * @sample com.example.MyClass.sampleUsage
 * @see [External Reference](https://example.com/api)
 */
```text

**Required:**

- Public classes and interfaces
- Public functions
- Complex internal logic

### 2.3 Code Documentation Quality Checks

**For all code files:**

1. **Header documentation exists** for:
   - Functions (what it does, params, returns)
   - Classes (purpose, usage)
   - Modules/files (purpose, exports)

2. **Focus validation**:
   - ✅ WHAT: Clear description of functionality
   - ✅ WHAT: Parameter descriptions
   - ✅ WHAT: Return value descriptions
   - ⚠️ WHY: Only for non-obvious implementations
   - ❌ HOW: Avoid describing code line-by-line

3. **External references**:
   - Validate HTTP links are accessible
   - Check links point to current documentation (not outdated)
   - Ensure links are relevant and useful

4. **Examples**:
   - Include for complex functions
   - Show typical usage
   - Keep examples short (< 10 lines)

**Bad documentation examples:**

```typescript
// ❌ WRONG - Describes WHAT code does line-by-line
/**
 * This function first checks if input is null, then creates
 * a new array, loops through items, and returns result
 */

// ❌ WRONG - Vague and useless
/**
 * Processes data
 */

// ✅ CORRECT - Describes WHAT and WHEN
/**
 * Validates user input against schema constraints
 *
 * @param input - Raw user input to validate
 * @param schema - JSON schema for validation rules
 * @returns true if valid, false otherwise
 * @throws {ValidationError} When schema is malformed
 */
```text

## Phase 3: Execute Linting (if available)

### 3.1 Scoped Linting with Taskfile

If Taskfile detected with FILES support:

```bash
# Collect files to lint
FILES="file1.md,file2.ts,file3.py"

# Run scoped lint
task lint FILES="$FILES"
```text

**Benefits:**

- Faster than full project lint
- Uses project's lint configuration
- Respects gitignore automatically
- Consistent with development workflow

### 3.2 Language-Specific Linting

**TypeScript/JavaScript:**

```bash
npx eslint --format unix "$FILES"
```text

**Python:**

```bash
pylint "$FILES" || flake8 "$FILES"
```text

**Kotlin:**

```bash
./gradlew ktlintCheck || mvn ktlint:check
```text

### 3.3 Markdown Linting

```bash
npx markdownlint-cli2 "$FILES"
```text

## Phase 4: Generate Report

Create `.docs.report.local.md`:

```markdown
# Documentation & Code Review Report

**Generated:** [ISO timestamp]
**Context:** [Staged changes | Uncommitted changes | Glob pattern]
**Files Reviewed:** [count]
**Standards Guide:** [docs/guides/agents.markdown.md](../guides/agents.markdown.md)
**Gitignored Files:** [count] files skipped

## Summary

**Total Files:** [count]
- Markdown: [count]
- TypeScript/JavaScript: [count]
- Python: [count]
- Kotlin: [count]

**Review Results:**
- ✅ Clean: [count]
- ⚠️ Warnings: [count]
- ❌ Issues: [count]

**Overall Status:** [✅ PASS | ❌ FAIL | ⚠️ WARNINGS]

---

## Markdown Files

### Standards Applied

Reference: [docs/guides/agents.markdown.md](../guides/agents.markdown.md)

Key standards:
- No emojis in headers
- No checkbox lists
- No AI adjectives (robust, comprehensive, seamless)
- Audience awareness for international teams
- Collapsible sections for lengthy content

### [filename.md](path/to/filename.md)

**Status:** [✅ Clean | ⚠️ Warnings | ❌ Issues]
**Lines:** [count]

**Standards Violations:**
- Line [N]: Emoji in header: `## ✅ Installation`
- Line [N]: Checkbox syntax detected: `- [x] Complete`
- Line [N]: AI adjective: "robust solution"
- Line [N]: Undefined acronym: "CDN"
- Lines [N-M]: Code block (50 lines) should use `<details>`

**Link Issues:**
- Line [N]: Broken link: [text](broken/path.md)
- Line [N]: External link returns 404: https://example.com/missing

**Recommendations:**
1. Remove emoji from header (line [N])
2. Replace checkbox with grouped sections
3. Define CDN on first use: "CDN (Content Delivery Network)"
4. Wrap code block in collapsible section

---

## Code Files

### TypeScript/JavaScript

#### [filename.ts](path/to/filename.ts)

**Status:** [✅ Clean | ⚠️ Warnings | ❌ Issues]

**File-Level Documentation:**
- [✅ Present | ⚠️ Missing | ⚠️ Incomplete]
- Placement: [After copyright, before imports | ❌ Wrong location]
- References: [N] external links, [N] internal references
- Link validation: [All valid | ⚠️ [N] broken]

**Missing Documentation:**
- Line [N]: Function `processData` lacks TSDoc comment
- Line [N]: Public method `validate` undocumented
- Line [N]: Exported class `DataProcessor` missing class doc

**Documentation Issues:**
- Line [N]: Missing @param for `options` parameter
- Line [N]: Missing @returns description
- Line [N]: No @throws for error conditions
- Line [1]: File-level documentation missing for infrastructure file
- Line [5]: File-level documentation should appear before imports

**Link Validation:**
- Line [N]: Broken reference: https://example.com/api/old (404)
- Line [3]: File-level @see link broken: https://docs.example.com (404)

**Good Examples:**
- Line [1]: File-level documentation includes purpose, responsibilities, and references
- Line [N]: `calculateMetrics` - Well documented with example

**Recommendations:**
1. Add file-level documentation (lines 1-15) explaining purpose and responsibilities
2. Add TSDoc comment for `processData` (line [N])
3. Document error conditions with @throws
4. Update broken API reference links
5. Add @see references to related modules

### Python

#### [filename.py](path/to/filename.py)

**Status:** [✅ Clean | ⚠️ Warnings | ❌ Issues]

**File-Level Documentation:**
- [✅ Present | ⚠️ Missing | ⚠️ Incomplete]
- Placement: [After copyright, before imports | ❌ Wrong location]
- References: [N] external links in "See Also" section
- Link validation: [All valid | ⚠️ [N] broken]

**Missing Documentation:**
- Line [N]: Function `process_data` lacks docstring
- Line [N]: Class `DataProcessor` missing class docstring
- Line [1]: Module-level docstring missing

**Documentation Issues:**
- Line [N]: Missing Args section for parameters
- Line [N]: Missing Returns section
- Line [N]: Undocumented exception: `ValueError`
- Line [3]: Module docstring should include "See Also" references

**Style:** [Google | NumPy]

**Recommendations:**
1. Add module-level docstring explaining file purpose and key responsibilities
2. Add docstring with Args/Returns/Raises sections to functions
3. Document ValueError conditions
4. Include "See Also" references to related modules and external docs

### Kotlin

#### [filename.kt](path/to/filename.kt)

**Status:** [✅ Clean | ⚠️ Warnings | ❌ Issues]

**File-Level Documentation:**
- [✅ Present | ⚠️ Missing | ⚠️ Incomplete]
- Placement: [After copyright, before package | ❌ Wrong location]
- References: [N] @see links to external/internal docs
- Link validation: [All valid | ⚠️ [N] broken]

**Missing Documentation:**
- Line [N]: Public function `processData` lacks KDoc
- Line [N]: Data class `User` missing class documentation
- Line [1]: File-level KDoc missing

**Documentation Issues:**
- Line [N]: Missing @param descriptions
- Line [N]: Missing @return description
- Line [5]: File-level documentation should appear before package declaration

**Recommendations:**
1. Add file-level KDoc explaining file purpose and architecture context
2. Add KDoc for public functions with @param and @return tags
3. Document data class purpose and fields
4. Include @see references to related classes and external documentation

---

## Linting Results

**Taskfile:** [Detected | Not found]
**Scoped Linting:** [Used | Not available]

### Markdown Lint
- **Tool:** markdownlint-cli2
- **Issues:** [count]
- **Auto-fixable:** [count]

### Code Lint
- **TypeScript:** [pass/fail] ([count] issues)
- **Python:** [pass/fail] ([count] issues)
- **Kotlin:** [pass/fail] ([count] issues)

---

## External Link Validation

**Total Links:** [count]
**Checked:** [count]
**Broken:** [count]

**Broken Links:**
- [file.md](file.md) line [N]: https://example.com/missing (404)
- [file.ts](file.ts) line [N]: https://api.example.com/v1/docs (timeout)

---

## Recommendations

### 🔴 Critical (Must Fix)

**Markdown:**
1. [file.md](file.md): Remove emojis from headers (lines [N-M])
2. [file.md](file.md): Replace checkbox lists (lines [N-M])
3. [file.md](file.md): Fix broken links (3 links)

**Code Documentation:**
1. [file.ts](file.ts): Document exported functions (5 missing)
2. [file.py](file.py): Add docstrings to public methods (3 missing)
3. [sst.config.ts](sst.config.ts): Add file-level documentation (infrastructure entrypoint)

### 🟡 High Priority

1. Add file-level documentation to core business logic files
2. Define abbreviations on first use (CDN, API, etc.)
3. Update broken external documentation links
4. Add examples to complex functions
5. Include @see/@link references in file-level documentation

### 🟢 Low Priority

1. Consider adding more code examples
2. Improve parameter descriptions
3. Run `/docs --fix` for auto-fixes

---

## Auto-Fixes Applied

[Only if --fix flag used]

**Markdown:**
- [file.md](file.md): Fixed heading hierarchy (2 issues)
- [file.md](file.md): Added code block language tags (4 blocks)

**Code:**
- [file.ts](file.ts): Added missing TSDoc tags (3 functions)

**Could not auto-fix:**
- Broken links (requires link correction)
- Missing function descriptions (requires human input)

---

## Collapsible Sections Applied

[Only if --collapse flag used]

**Summary:**
- Files processed: [N]
- Code blocks collapsed: [N] (10+ lines)
- Step-by-step procedures collapsed: [N] (5+ steps)
- Long lists collapsed: [N] (10+ items)
- Troubleshooting sections collapsed: [N]
- Advanced/optional sections collapsed: [N]

**Details:**

### [file.md](file.md)

**Collapsed:**
- Lines [N-M]: Code block (15 lines) → `<details><summary><strong>Example: Database Setup</strong></summary>`
- Lines [N-M]: Numbered list (7 steps) → Wrapped each step in `<details><summary><strong>Step N: [Action]</strong></summary>`
- Lines [N-M]: Troubleshooting section → `<details><summary><strong>Troubleshooting: Connection Timeout</strong></summary>`
- Lines [N-M]: Long list (12 items) → `<details><summary><strong>Available Environment Variables</strong></summary>`

**Kept Visible:**
- Lines [N-M]: Short code block (5 lines) - below 10-line threshold
- Lines [N-M]: Table with metrics - tables remain visible per guidelines
- Lines [N-M]: Prerequisites list (3 items) - below 10-item threshold
- Lines [N-M]: Mermaid diagram - diagrams remain visible

**Could not collapse:**
- Lines [N-M]: Code block already in `<details>` tags
- Lines [N-M]: Nested details (3+ levels) - restructuring needed

---

## Next Steps

**If critical issues:**
- [ ] Review markdown standards in [agents.markdown.md](../guides/agents.markdown.md)
- [ ] Remove emojis from headers
- [ ] Replace checkbox lists with grouped sections
- [ ] Document exported functions/classes
- [ ] Fix broken links
- [ ] Re-run: `/docs --staged --compare`

**If warnings only:**
- [ ] Run `/docs --fix` for auto-fixes
- [ ] Run `/docs --collapse` to apply collapsible section rules
- [ ] Review diff and commit

**If all clean:**
- [ ] Documentation meets standards ✅
- [ ] Ready to commit

---

**Report Location:** `.docs.report.local.md`
**Standards Guide:** [docs/guides/agents.markdown.md](../guides/agents.markdown.md)
**Review Command:** `/docs $ARGUMENTS`
```text

## Phase 5: Present Results

**Print summary to console:**

```text
Documentation & Code Review

Context: [Staged changes | Uncommitted | Pattern]
Files Reviewed: [N]
  Markdown: [N]
  Code: [N]
  Gitignored: [N] (skipped)

Status:
  ✅ Clean: [N]
  ⚠️ Warnings: [N]
  ❌ Issues: [N]

[If --collapse used]
Collapsible Sections Applied: [N]
  Code blocks: [N]
  Step procedures: [N]
  Long lists: [N]
  Troubleshooting: [N]

Critical Issues:
  - [file.md]: Emojis in headers, checkbox lists
  - [file.ts]: Missing function documentation

Report: .docs.report.local.md
Standards: docs/guides/agents.markdown.md
```text

**Exit codes:**

- 0: All files pass
- 1: Critical issues (standards violations, missing docs)
- 2: Warnings only
- 3: No files in scope

## Error Handling

**Standards guide missing:**

- Warn but continue with basic checks
- Note in report with path where it should be

**Linter unavailable:**

- Use manual validation
- Provide installation instructions in report

**Gitignore check fails:**

- Assume file is tracked
- Continue with review

**Link validation fails:**

- Note as warning, not error
- Continue with remaining checks

**Taskfile not found:**

- Fall back to individual linters
- Note in report

## Examples

```bash
# Review staged changes (pre-commit)
/docs --staged

# Review uncommitted changes
/docs --diff

# Review specific files
/docs src/utils/logger.ts docs/README.md

# Review and auto-fix
/docs --staged --fix

# Review docs directory only
/docs docs/**/*.md

# Strict mode (stop on first issue)
/docs --staged --strict

# Compare with previous review
/docs --staged --compare

# Apply collapsible sections to specific files
/docs docs/**/*.md --collapse

# Fix and collapse in one pass
/docs --staged --fix --collapse

# Collapse specific documentation files
/docs README.md docs/guides/deployment.md --collapse
````