| 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:
- Reading all design docs for a module (or all modules)
- Analyzing frontmatter completeness and accuracy
- Checking documentation quality and thoroughness
- Identifying missing or outdated content
- Finding broken cross-references
- Assessing status progression and maintenance
- 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
- Parse Parameters - Extract target and options
- Load Configuration - Read config for module paths and standards
- Find Documents - Glob all markdown files (skip
_ prefixed)
- Analyze Each Document - Run health checks (see
analysis-checks.md)
- Calculate Scores - Compute health scores (see
scoring-reports.md)
- Generate Report - Create comprehensive findings report
- 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
