documentation-review— agent skill

Documentation Review Skill

This skill proactively identifies documentation issues and suggests fixes for the u-he-preset-randomizer project.

When to Activate

Automatically trigger this skill when:

• User mentions documentation being out of date
• User asks about API examples or how to use features
• After making significant changes to exported functions or public APIs
• When user mentions adding features that need documentation
• User asks to review or update docs
• After modifying CLI flags or MCP tools

Project Context

u-he-preset-randomizer - CLI tool and MCP server for u-he synth preset generation:

• CLI interface (src/cli.ts) - Main command-line tool
• MCP server (src/mcp-server.ts) - Model Context Protocol server for AI assistants
• Core modules: parser, analyzer, randomizer, preset library
• Synth support: Diva, Hive, Repro-1, Repro-5, Zebra2, ZebraHZ, Zebralette3, and more

Quick Documentation Checks

#### 1. Core Documentation Files

• README.md - Installation, CLI usage, MCP setup
• MCP_SERVER.md - MCP tool documentation and examples
• AGENTS.md - Development architecture and workflows
• CHANGELOG.md - Version history (current: 1.1.2)

#### 2. CLI Examples Validation

Verify examples use correct flags:

• --synth - Synth name (e.g., Diva, Hive)
• --amount - Number of presets to generate
• --randomness - Percentage (0-100) for randomization
• --preset - Base preset name or ? for random
• --merge - Preset names to merge (can be multiple)
• --pattern - Glob pattern for preset filtering
• --folder - Filter by folder path
• --category - Filter by category
• --author - Filter by author
• --favorites - Filter by .uhe-fav file
• --stable - Use stable randomization mode
• --binary - Include binary section (⚠️ may cause crashes)
• --dictionary - Use dictionary for random names
• --custom-folder - Custom u-he installation path
• --debug - Enable debug logging

#### 3. MCP Tool Signatures

Verify MCP_SERVER.md examples match src/mcp-server.ts:

• list_synths - Detect available synths
• select_synth - Load preset library (with optional pattern)
• get_current_synth - Get active synth info
• list_presets - List with pagination
• search_presets - Fuzzy search
• filter_presets - Filter by category/author/favorites/pattern
• explain_preset - Get preset details
• get_categories, get_authors, get_favorites_files - Metadata helpers
• generate_random_presets - Generate from distributions
• randomize_presets - Create variations
• merge_presets - Blend multiple presets
• get_synth_context - Get synth reference docs

#### 4. Source Code Documentation

All TypeScript files must have `@file` headers:

/**
 * @file Brief description of module's purpose.
 */

Exported functions need JSDoc (if not obvious from types):

/**
 * Function description explaining what it does.
 *
 * @param paramName - Parameter description
 * @returns What the function returns
 * @throws {Error} When it throws errors
 */
export function myFunction(paramName: string): ReturnType { ... }

Key files to document:

• src/index.ts - Public API exports
• src/parser.ts - Preset parsing/serialization (public API)
• src/cli.ts - CLI entry point
• src/mcp-server.ts - MCP server
• src/generatePresets.ts - Main generation function
• All other src/*.ts files

Actions When Issues Detected

1. Small issues (typos, outdated examples, missing headers):

• Fix immediately and explain what was corrected
• Validate with npm run lint && npm run typecheck

2. Medium issues (multiple outdated sections, missing documentation):

• List all issues found
• Propose specific fixes
• Ask if user wants them all fixed at once

3. Major issues (significant inconsistencies, large gaps):

• Explain the scope of issues
• Suggest running full documentation review: /documentation
• Wait for user approval before proceeding

Formatting Standards

@file Headers:

// Entry points
/**
 * @file CLI entry point for u-he preset randomizer tool.
 * Handles argument parsing, interactive mode, and orchestration.
 */

// Core modules
/**
 * @file Preset parser and serializer for u-he preset files.
 * Provides functions to read, parse, and write .h2p preset files.
 */

// Utilities
/**
 * @file Utility functions for preset validation.
 */

JSDoc for Public Functions:

/**
 * Parses a u-he preset file into a structured object.
 *
 * @param fileString - The content of the preset file
 * @param filePath - Path to the file (for error messages)
 * @param binary - Whether to include binary section
 * @returns Parsed preset object with metadata and parameters
 */
export function parseUhePreset(
  fileString: string,
  filePath: string,
  binary: boolean,
): Preset { ... }

Avoid redundant JSDoc:

// ❌ Don't document what's obvious from types
/**
 * Gets the preset name
 * @param preset - The preset
 * @returns The name
 */
function getName(preset: Preset): string { ... }

// ✅ Let TypeScript speak for simple functions
function getName(preset: Preset): string { ... }

Validation Steps

After any documentation changes:

npm run lint          # Biome linting (must pass)
npm run typecheck     # TypeScript type checking (must pass)
npm run test:unit     # Unit tests (must pass)

Optional build check:

npm run build:dist    # Production build (for major changes)

Constraints

Never modify:

• Runtime logic or algorithm implementations
• Test assertions or test data
• Type definitions or interfaces
• Build configuration (tsconfig.json, biome.json, package.json)
• CI/CD workflows or git hooks

Always ask before:

• Major documentation restructuring
• Adding new documentation files
• Changing public API examples that users might depend on

Auto-fix these safely:

• Typos and grammar in markdown files
• Outdated CLI/MCP flag examples
• Missing @file headers
• Broken internal links
• Version numbers to match package.json

Integration with Full Review

For comprehensive reviews, this skill guides the user to use:

/documentation

Which performs:

• Complete scan of all documentation files
• All source file header checks
• Validation suite
• Structured summary of changes