design-review

name	design-review
description	Review and analyze design docs for health, quality, and improvement opportunities. Use when auditing design documentation, checking doc health, or identifying areas for improvement.
allowed-tools	Read, Glob, Bash(grep *)
context	fork
agent	design-doc-agent

Design Documentation Review

Analyzes design documentation for health, quality, and actionable improvement opportunities.

Overview

This skill performs comprehensive health checks on design documentation by:

1. Reading all design docs for a module (or all modules)
2. Analyzing frontmatter completeness and accuracy
3. Checking documentation quality and thoroughness
4. Identifying missing or outdated content
5. Finding broken cross-references
6. Assessing status progression and maintenance
7. Providing prioritized recommendations

Quick Start

Review single module:

/design-docs:design-review effect-type-registry

Review all modules:

/design-docs:design-review all

Detailed analysis:

/design-docs:design-review all --verbose

Focus on specific aspect:

/design-docs:design-review rspress-plugin-api-extractor --focus=completeness

Parameters

Required

• target - Module name to review, or "all" for all modules

Optional

• verbose - Show detailed analysis (default: false)
• focus - Specific aspect: completeness | quality | references | maintenance

Workflow Overview

1. Parse Parameters - Extract target and options
2. Load Configuration - Read config for module paths and standards
3. Find Documents - Glob all markdown files (skip _ prefixed)
4. Analyze Each Document - Run health checks (see analysis-checks.md)
5. Calculate Scores - Compute health scores (see scoring-reports.md)
6. Generate Report - Create comprehensive findings report
7. Focus Reports - Generate targeted analysis if focus specified

Supporting Documentation

For Analysis Criteria

See analysis-checks.md for:

• Frontmatter health check criteria (status, completeness, staleness)
• Content quality assessment rules (overview, rationale, implementation)
• Structure validation requirements (sections, TOC, formatting)
• Cross-reference validation logic (related, dependencies, links)
• Maintenance health indicators (abandonment, duplication, scope)

Load when: Performing detailed document analysis or diagnosing specific issues

For Scoring and Reports

See scoring-reports.md for:

• Health score calculation formulas (4 components: completeness, recency, quality, references)
• Scoring rubrics for each component (0-100 scale)
• Report format templates (executive summary, findings, recommendations)
• Priority classification system (critical, warning, info)
• Recommendation frameworks (impact/effort matrix)

Load when: Computing health scores or generating reports

For Usage Examples

See examples.md for:

• Complete usage scenarios (basic, verbose, focused reviews)
• Example outputs for different review types
• Focus-specific reports (completeness, quality, references, maintenance)
• Success report format

Load when: User wants to see concrete examples or needs clarification on output format

Health Score Components

Overall Health = (Completeness + Recency + Quality + References) / 4

• 🟢 Healthy (80-100): Well-maintained, comprehensive documentation
• 🟡 Needs Attention (60-79): Some issues, improvement recommended
• 🔴 Critical (<60): Significant issues, immediate action required

Integration

Use this skill with:

• /design-docs:design-validate - Fix structural/frontmatter issues first
• /design-docs:design-update - Apply recommended improvements
• /design-docs:design-sync - Address staleness and sync issues
• /design-docs:design-prune - Remove historical cruft identified in review

Success Criteria

A successful review:

• ✅ Analyzes all docs in target module(s)
• ✅ Identifies critical issues requiring immediate action
• ✅ Provides specific, actionable recommendations
• ✅ Calculates accurate health scores
• ✅ Prioritizes improvements by impact and effort
• ✅ Gives clear next steps