Design Documentation Comprehensive Audit
Performs deep quality audits of design documentation, checking structure,
content, relationships, and compliance with standards.
Overview
This skill provides comprehensive quality auditing for design documentation
by running all validation checks, analyzing content quality, verifying
cross-reference integrity, checking sync status, and generating detailed
audit reports with prioritized recommendations.
Quick Start
Audit all modules:
/design-audit
Audit specific module:
/design-audit effect-type-registry
Quick audit (non-strict):
/design-audit --strict=false
Parameters
Optional
module: Limit to specific module (default: all)strict: Enable strict mode (default: true)include-archived: Include archived docs (default: false)output: Output file path for report
Workflow
High-level audit process:
- Parse parameters to determine audit scope and strictness
- Load design.config.json to get quality standards and validation rules
- Discover documents across target modules using Glob
- Run validation checks (frontmatter, structure, content, references, sync)
- Analyze content quality (completeness, depth, examples, rationale)
- Check cross-references for broken links and circular dependencies
- Verify sync status with codebase alignment
- Calculate health scores (document, module, overall)
- Identify issues by severity (critical, high, medium, low)
- Generate audit report with findings and recommendations
- Provide recommendations prioritized by impact and effort
For detailed implementation steps, see supporting documentation below.
Supporting Documentation
When you need detailed information, load the appropriate supporting file:
For Detailed Workflow
See instructions.md for:
- Complete step-by-step audit workflow
- Document discovery and collection
- Validation check execution
- Content quality analysis algorithms
- Cross-reference integrity verification
- Sync status checking
- Health score calculation formulas
- Issue identification and severity assignment
- Report generation (Markdown, JSON, HTML)
- Recommendation prioritization
- Advanced features (trends, automated fixes, custom checks)
Load when: Performing audits or need implementation details
For Validation Checks
See checks.md for:
- Frontmatter validation rules (required fields, dates, cross-references)
- Structure validation (sections, headings, hierarchy)
- Content quality checks (completeness, depth, examples)
- Cross-reference integrity (broken links, circular dependencies)
- Sync status thresholds and scoring
- Technical debt detection (TODOs, incomplete sections)
- Overall health scoring formulas and weights
- Health rating ranges (A-F grades)
- Strict mode additional checks
Load when: Need check specifications, scoring details, or validation rules
For Usage Examples
See examples.md for:
- Full audit of all modules
- Module-specific audit in strict mode
- Quick audit without archived docs
- Audit with JSON output
- Example findings (critical, high, medium, low)
- Report format examples (Markdown, JSON, HTML)
Load when: User needs examples or clarification
Error Handling
No Documents Found
INFO: No design documents found to audit
Scope: {module}
This is normal for new modules. Run /design-init to create your first
design doc.
All Checks Passed
SUCCESS: All audit checks passed!
Overall Health: {score}/100 ({rating})
No issues found.
Integration
Works well with:
/design-validate - Run validation before full audit/design-review - Review issues found in audit/design-sync - Fix sync issues identified/design-update - Address content quality issues/design-report - Compare audit with health report
Success Criteria
A successful audit:
- ✅ All documents discovered and analyzed
- ✅ All validation checks executed
- ✅ Content quality assessed
- ✅ Cross-references verified
- ✅ Sync status checked
- ✅ Health scores calculated accurately
- ✅ Issues categorized by severity
- ✅ Clear, actionable recommendations provided
- ✅ Comprehensive report generated
1---2name: design-audit3description: Comprehensive health audit for design documentation. Use when performing thorough quality checks, preparing for releases, or ensuring documentation compliance.4---5
6# Design Documentation Comprehensive Audit
7
8Performs deep quality audits of design documentation, checking structure,
9content, relationships, and compliance with standards.
10
11## Overview
12
13This skill provides comprehensive quality auditing for design documentation
14by running all validation checks, analyzing content quality, verifying
15cross-reference integrity, checking sync status, and generating detailed
16audit reports with prioritized recommendations.
17
18## Quick Start
19
20**Audit all modules:**
21
22```bash
23/design-audit
24```
25
26**Audit specific module:**
27
28```bash
29/design-audit effect-type-registry
30```
31
32**Quick audit (non-strict):**
33
34```bash
35/design-audit --strict=false
36```
37
38## Parameters
39
40### Optional
41
42- `module`: Limit to specific module (default: all)
43- `strict`: Enable strict mode (default: true)
44- `include-archived`: Include archived docs (default: false)
45- `output`: Output file path for report
46
47## Workflow
48
49High-level audit process:
50
511. **Parse parameters** to determine audit scope and strictness
522. **Load design.config.json** to get quality standards and validation rules
533. **Discover documents** across target modules using Glob
544. **Run validation checks** (frontmatter, structure, content, references, sync)
555. **Analyze content quality** (completeness, depth, examples, rationale)
566. **Check cross-references** for broken links and circular dependencies
577. **Verify sync status** with codebase alignment
588. **Calculate health scores** (document, module, overall)
599. **Identify issues** by severity (critical, high, medium, low)
6010. **Generate audit report** with findings and recommendations
6111. **Provide recommendations** prioritized by impact and effort
62
63For detailed implementation steps, see supporting documentation below.
64
65## Supporting Documentation
66
67When you need detailed information, load the appropriate supporting file:
68
69### For Detailed Workflow
70
71See [instructions.md](instructions.md) for:
72
73- Complete step-by-step audit workflow
74- Document discovery and collection
75- Validation check execution
76- Content quality analysis algorithms
77- Cross-reference integrity verification
78- Sync status checking
79- Health score calculation formulas
80- Issue identification and severity assignment
81- Report generation (Markdown, JSON, HTML)
82- Recommendation prioritization
83- Advanced features (trends, automated fixes, custom checks)
84
85**Load when:** Performing audits or need implementation details
86
87### For Validation Checks
88
89See [checks.md](checks.md) for:
90
91- Frontmatter validation rules (required fields, dates, cross-references)
92- Structure validation (sections, headings, hierarchy)
93- Content quality checks (completeness, depth, examples)
94- Cross-reference integrity (broken links, circular dependencies)
95- Sync status thresholds and scoring
96- Technical debt detection (TODOs, incomplete sections)
97- Overall health scoring formulas and weights
98- Health rating ranges (A-F grades)
99- Strict mode additional checks
100
101**Load when:** Need check specifications, scoring details, or validation rules
102
103### For Usage Examples
104
105See [examples.md](examples.md) for:
106
107- Full audit of all modules
108- Module-specific audit in strict mode
109- Quick audit without archived docs
110- Audit with JSON output
111- Example findings (critical, high, medium, low)
112- Report format examples (Markdown, JSON, HTML)
113
114**Load when:** User needs examples or clarification
115
116## Error Handling
117
118### No Documents Found
119
120```text
121INFO: No design documents found to audit
122
123Scope: {module}
124
125This is normal for new modules. Run /design-init to create your first
126design doc.
127```
128
129### All Checks Passed
130
131```text
132SUCCESS: All audit checks passed!
133
134Overall Health: {score}/100 ({rating})
135No issues found.
136```
137
138## Integration
139
140Works well with:
141
142- `/design-validate` - Run validation before full audit
143- `/design-review` - Review issues found in audit
144- `/design-sync` - Fix sync issues identified
145- `/design-update` - Address content quality issues
146- `/design-report` - Compare audit with health report
147
148## Success Criteria
149
150A successful audit:
151
152- ✅ All documents discovered and analyzed
153- ✅ All validation checks executed
154- ✅ Content quality assessed
155- ✅ Cross-references verified
156- ✅ Sync status checked
157- ✅ Health scores calculated accurately
158- ✅ Issues categorized by severity
159- ✅ Clear, actionable recommendations provided
160- ✅ Comprehensive report generated
majiayu000