/documentation

allowed-tools: Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git rev-parse:*), Bash(git branch:*), Read, Grep, Glob, TodoWrite
description: Check for documentation standards violations

/review:documentation - Documentation Standards Checker

You are reviewing code changes for violations of **documentation standards**.

The Principle

All major files, classes, and functionality must have documentation. Documentation helps both humans and LLMs understand code purpose and usage.

**Key requirements:**

• File-level comments explaining purpose
• JSDoc for complex functions/hooks
• Inline comments for non-obvious logic
• TODOs with context

Phase 1: Gather Context

# Get current branch
git rev-parse --abbrev-ref HEAD

# Get changed files
git diff main...HEAD --name-only

# Get new files (these MUST have documentation)
git diff main...HEAD --name-status | grep "^A"

# Get full diff
git diff main...HEAD

Use TodoWrite to track files needing documentation review.

Phase 2: Check Documentation Standards

2.1 File-Level Documentation

**Every new file should have a top comment:**

// CORRECT - Service with purpose
/**
 * FeedService handles all feed-related operations including
 * fetching, filtering, and updating feed items.
 */
export class FeedService extends BaseService {
  // ...
}

// CORRECT - Hook with purpose and usage
/**
 * useFeedPage orchestrates the feed page state and actions.
 *
 * Combines feed data fetching, filtering, and user actions
 * into a single hook for the FeedPage component.
 *
 * @example
 * const { items, isLoading, handleRefresh } = useFeedPage();
 */
export function useFeedPage() {
  // ...
}

// CORRECT - Component with purpose
/**
 * DictationButton provides voice-to-text input functionality.
 *
 * Displays a microphone button that starts/stops dictation,
 * shows a waveform during recording, and handles errors.
 *
 * Sizes: 'sm' (compact), 'md' (default), 'lg' (prominent)
 */
export function DictationButton({ size = 'md', ...props }) {
  // ...
}

// WRONG - No file documentation
export class FeedService extends BaseService {
  // ...
}

2.2 Complex Function Documentation

**Functions with non-obvious behavior need JSDoc:**

// CORRECT - Complex function documented
/**
 * Calculates the optimal batch size for audio processing.
 *
 * Uses a heuristic based on available memory and audio duration
 * to prevent OOM errors while maximizing throughput.
 *
 * @param audioDuration - Duration in seconds
 * @param availableMemory - Available memory in bytes
 * @returns Optimal batch size (1-100)
 */
function calculateBatchSize(audioDuration: number, availableMemory: number): number {
  // Complex calculation...
}

// WRONG - Complex logic without explanation
function calculateBatchSize(audioDuration: number, availableMemory: number): number {
  return Math.min(100, Math.max(1, Math.floor(availableMemory / (audioDuration * 1024 * 1024))));
}

2.3 Inline Comments for Non-Obvious Logic

**Explain the "why", not the "what":**

// CORRECT - Explains why
// Wait 150ms for final WebSocket transcript update before completing
await new Promise(resolve => setTimeout(resolve, 150));

// Use mutex ref to prevent rapid double-clicks from starting multiple sessions
if (startingRef.current) return;
startingRef.current = true;

// WRONG - States the obvious
// Set loading to true
setLoading(true);

// Call the API
const result = await api.fetch();

2.4 TODO Standards

**TODOs must have context:**

// CORRECT - TODO with context
// TODO(#123): Add retry logic for network failures
// TODO(@username): Refactor after API v2 migration

// WRONG - Orphaned TODO
// TODO: fix this
// TODO: do something

2.5 Hook Documentation

**Hooks should document their purpose and return values:**

// CORRECT
/**
 * useDictation manages voice dictation recording and transcription.
 *
 * Handles:
 * - Microphone access and MediaStream management
 * - WebSocket connection for real-time transcription
 * - Recording state machine (idle → connecting → recording → stopping)
 *
 * @param options.workspaceId - Workspace for transcription context
 * @param options.onComplete - Called with final transcript when stopped
 *
 * @returns {Object} Dictation controls and state
 * @returns {boolean} isRecording - Whether actively recording
 * @returns {boolean} isConnecting - Whether establishing connection
 * @returns {Function} start - Begin dictation
 * @returns {Function} stop - End dictation and trigger onComplete
 */
export function useDictation(options: UseDictationOptions): UseDictationReturn {
  // ...
}

2.6 Component Props Documentation

**Complex props should be documented:**

// CORRECT
interface DictationButtonProps {
  /** Button size variant */
  size?: 'sm' | 'md' | 'lg';
  /** Workspace ID for transcription context */
  workspaceId: string;
  /** Called when dictation completes with transcript */
  onComplete?: (transcript: string) => void;
  /** Whether the button is disabled */
  disabled?: boolean;
}

// Also acceptable - inline comments
interface DictationButtonProps {
  size?: 'sm' | 'md' | 'lg';  // Button size variant
  workspaceId: string;         // Workspace for transcription
  onComplete?: (transcript: string) => void;
  disabled?: boolean;
}

Phase 3: Generate Report

# Documentation Standards Report

**Branch:** {branch}
**Status:** {PASS | WARN | FAIL}

## Summary

{One sentence assessment of documentation quality}

## Files Checked

- **New files:** {count}
- **Modified files:** {count}
- **Files needing documentation:** {count}

## Documentation Issues

### Critical (Must Fix)

| File | Issue |
|------|-------|
| {file} | New file missing file-level documentation |
| {file} | Complex function without JSDoc |

### Warnings

| Location | Issue | Suggestion |
|----------|-------|------------|
| {file:line} |