documentation

name	documentation
description	This skill should be used when reviewing for documentation drift, missing API docs, or stale comments.
user-invocable	false
allowed-tools	Read, Grep, Glob

Documentation Patterns

Domain expertise for documentation quality and alignment. Use alongside devflow:review-methodology for complete documentation reviews.

Iron Law

DOCUMENTATION MUST MATCH REALITY

Outdated documentation is worse than no documentation. It actively misleads. Every code change that affects behavior requires a documentation check. Comments that explain "what" instead of "why" are noise. The best documentation is code that doesn't need documentation.

---

Documentation Categories

1. Code Documentation Issues

Issue	Problem	Fix
Missing docstrings	Complex functions without explanation	Add JSDoc with params, returns, throws
Outdated comments	Comments that contradict code	Update or remove
"What" comments	// Loop through users	Explain "why" instead
Magic algorithms	Complex logic without explanation	Document algorithm and rationale
Transition residue	"We no longer do X" notes, in-file changelogs, or refs to removed code/sections	Remove — git holds the history

Brief Example - Missing vs. Complete:

// BAD: No documentation on complex function
export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;

// GOOD: Purpose, params, returns, edge cases documented
/**
 * Calculates prorated billing amount when switching plans mid-cycle.
 * @param plan - The new plan to prorate to
 * @returns Prorated amount in cents (can be negative for downgrades)
 */
export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;

2. API Documentation Issues

Issue	Problem	Fix
Missing params	Callers don't know valid values	Document all params with types and constraints
Missing returns	Return shape unknown	Describe return structure and units
Missing errors	Callers don't know what to catch	List all thrown error types

Brief Example - Incomplete vs. Complete:

// BAD: No params, no errors documented
/** Creates a subscription. */
async function createSubscription(userId: string, planId: string): Promise<Subscription>;

// GOOD: Full contract documented
/**
 * @param userId - User's unique identifier
 * @param planId - Plan ID from /plans endpoint
 * @throws {UserNotFoundError} If userId doesn't exist
 * @throws {PlanNotFoundError} If planId doesn't exist
 */
async function createSubscription(userId: string, planId: string): Promise<Subscription>;

3. Alignment Issues

Issue	Problem	Fix
Code-comment drift	Comment says 3 retries, code does 5	Update comment or use constant
Stale README	Examples use removed functions	Keep README in sync with code
Missing changelog	Breaking changes undocumented	Document all notable changes

Brief Example - Drift vs. Aligned:

// BAD: Comment doesn't match code
// Retries up to 3 times
for (let i = 0; i < 5; i++) { /* ... */ }

// GOOD: Use constant to keep aligned
const MAX_RETRIES = 5;
for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }

---

Extended References

For extended examples and detection commands:

• references/violations.md - Extended violation examples with explanations
• references/patterns.md - Complete correct pattern examples
• references/detection.md - Bash commands for finding issues

---

Severity Guidelines

Severity	Description	Examples
CRITICAL	Actively misleading	Comments contradict code; API docs with wrong types; README with broken steps; Changelog missing breaking changes
HIGH	Significant gaps	Public APIs undocumented; Complex algorithms unexplained; Errors not documented; Migration guides missing
MEDIUM	Moderate issues	Some params undocumented; Examples could be clearer; "What" comments instead of "why"
LOW	Minor improvements	Could add more examples; Formatting inconsistencies; Typos

---

Documentation Checklist

Before approving changes:

• All public APIs have JSDoc/docstrings
• Parameters and return values documented
• Error conditions documented
• Complex algorithms explained
• Comments explain "why", not "what"
• README reflects current state
• CHANGELOG updated for notable changes
• No TODO comments for completed work
• Examples work with current API