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-review effect-type-registry
Review all modules:
/design-review all
Detailed analysis:
/design-review all --verbose
Focus on specific aspect:
/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-validate - Fix structural/frontmatter issues first/design-update - Apply recommended improvements/design-sync - Address staleness and sync issues/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
1---2name: design-review3description: Review and analyze design docs for health, quality, and improvement opportunities. Use when auditing design documentation, checking doc health, or identifying areas for improvement.4---5
6# Design Documentation Review
7
8Analyzes design documentation for health, quality, and actionable improvement
9opportunities.
10
11## Overview
12
13This skill performs comprehensive health checks on design documentation by:
14
151. Reading all design docs for a module (or all modules)
162. Analyzing frontmatter completeness and accuracy
173. Checking documentation quality and thoroughness
184. Identifying missing or outdated content
195. Finding broken cross-references
206. Assessing status progression and maintenance
217. Providing prioritized recommendations
22
23## Quick Start
24
25**Review single module:**
26
27```bash
28/design-review effect-type-registry
29```
30
31**Review all modules:**
32
33```bash
34/design-review all
35```
36
37**Detailed analysis:**
38
39```bash
40/design-review all --verbose
41```
42
43**Focus on specific aspect:**
44
45```bash
46/design-review rspress-plugin-api-extractor --focus=completeness
47```
48
49## Parameters
50
51### Required
52
53- `target` - Module name to review, or "all" for all modules
54
55### Optional
56
57- `verbose` - Show detailed analysis (default: false)
58- `focus` - Specific aspect: completeness | quality | references | maintenance
59
60## Workflow Overview
61
621. **Parse Parameters** - Extract target and options
632. **Load Configuration** - Read config for module paths and standards
643. **Find Documents** - Glob all markdown files (skip `_` prefixed)
654. **Analyze Each Document** - Run health checks (see
66 [analysis-checks.md](analysis-checks.md))
675. **Calculate Scores** - Compute health scores (see
68 [scoring-reports.md](scoring-reports.md))
696. **Generate Report** - Create comprehensive findings report
707. **Focus Reports** - Generate targeted analysis if focus specified
71
72## Supporting Documentation
73
74### For Analysis Criteria
75
76See [analysis-checks.md](analysis-checks.md) for:
77
78- Frontmatter health check criteria (status, completeness, staleness)
79- Content quality assessment rules (overview, rationale, implementation)
80- Structure validation requirements (sections, TOC, formatting)
81- Cross-reference validation logic (related, dependencies, links)
82- Maintenance health indicators (abandonment, duplication, scope)
83
84**Load when:** Performing detailed document analysis or diagnosing specific
85issues
86
87### For Scoring and Reports
88
89See [scoring-reports.md](scoring-reports.md) for:
90
91- Health score calculation formulas (4 components: completeness, recency,
92 quality, references)
93- Scoring rubrics for each component (0-100 scale)
94- Report format templates (executive summary, findings, recommendations)
95- Priority classification system (critical, warning, info)
96- Recommendation frameworks (impact/effort matrix)
97
98**Load when:** Computing health scores or generating reports
99
100### For Usage Examples
101
102See [examples.md](examples.md) for:
103
104- Complete usage scenarios (basic, verbose, focused reviews)
105- Example outputs for different review types
106- Focus-specific reports (completeness, quality, references, maintenance)
107- Success report format
108
109**Load when:** User wants to see concrete examples or needs clarification on
110output format
111
112## Health Score Components
113
114Overall Health = (Completeness + Recency + Quality + References) / 4
115
116- 🟢 **Healthy** (80-100): Well-maintained, comprehensive documentation
117- 🟡 **Needs Attention** (60-79): Some issues, improvement recommended
118- 🔴 **Critical** (<60): Significant issues, immediate action required
119
120## Integration
121
122Use this skill with:
123
124- `/design-validate` - Fix structural/frontmatter issues first
125- `/design-update` - Apply recommended improvements
126- `/design-sync` - Address staleness and sync issues
127- `/design-prune` - Remove historical cruft identified in review
128
129## Success Criteria
130
131A successful review:
132
133- ✅ Analyzes all docs in target module(s)
134- ✅ Identifies critical issues requiring immediate action
135- ✅ Provides specific, actionable recommendations
136- ✅ Calculates accurate health scores
137- ✅ Prioritizes improvements by impact and effort
138- ✅ Gives clear next steps
majiayu000