| name | design-report |
| description | Generate status reports for design documentation. Use when creating documentation summaries, tracking progress, or preparing documentation reviews. |
| allowed-tools | Read, Glob, Bash(jq *) |
| context | fork |
| agent | design-doc-agent |
Design Documentation Status Reports
Generates comprehensive status reports for design documentation, including
progress metrics, health scores, and actionable recommendations.
Overview
This skill analyzes design documentation to provide insights into
documentation quality, completeness, and health. It calculates progress
metrics, assigns health scores, identifies issues (stale docs, orphans,
sync lag), and provides prioritized recommendations for improvement.
Quick Start
Full report:
/design-docs:design-report
Module-specific:
/design-docs:design-report effect-type-registry
JSON output:
/design-docs:design-report --format=json
Focus on health:
/design-docs:design-report --focus=health
Parameters
Optional
module: Limit to specific module (default: all)format: Output format (markdown, json, html) (default: markdown)focus: Report focus (progress, health, gaps, all) (default: all)include-archived: Include archived docs (default: false)
Workflow
High-level report generation process:
- Parse parameters to determine scope, format, and focus
- Load design.config.json to identify modules and quality standards
- Collect design documents using Glob, filtering by module and archive
status
- Parse metadata from frontmatter (status, completeness, dates,
references)
- Calculate progress metrics (overall, per-module, per-category)
- Assess health scores using weighted formula (completeness, status,
freshness, relationships)
- Identify issues (stale docs, orphans, incomplete, sync lag, missing
categories)
- Generate report in requested format with visualizations
- 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 report generation workflow
- Frontmatter parsing and derived metrics calculation
- Progress metrics formulas and aggregation
- Health score calculation with component weights
- Issue detection algorithms and severity assignment
- Report generation for each format
- Recommendation prioritization strategies
- Advanced features (trends, benchmarking, custom focus)
Load when: Generating reports or need implementation details
For Metrics Calculations
See metrics-calculation.md for:
- Progress metrics formulas (coverage, completeness, completion rate)
- Health score calculation with component weights
- Derived metrics (age, staleness, sync lag, velocity)
- Issue detection algorithms
- Trend analysis and benchmarking
Load when: Need formula details or implementing custom metrics
For Report Formats
See report-formats.md for:
- Markdown report structure and sections
- JSON schema and object format
- HTML template with CSS styling
- Format selection guidelines
Load when: Generating output or need format specifications
For Usage Examples
See examples.md for:
- Full report for all modules
- Module-specific progress report
- Health focus in JSON
- Documentation gaps report
- Module comparison
- Including archived documents
- Error scenarios (no docs, invalid frontmatter)
Load when: User needs examples or clarification
Error Handling
No Documents Found
INFO: No design documents found in {module}
This is normal for new modules. Run /design-docs:design-init to create your first
design doc.
Invalid Frontmatter
WARNING: Invalid frontmatter in {file}
Issue: {error-description}
Impact: Document excluded from report
Fix: Run /design-docs:design-validate {module} to identify and fix issues
Integration
Works well with:
/design-docs:design-review - Review docs flagged in report/design-docs:design-validate - Fix frontmatter issues/design-docs:design-update - Improve metrics by updating docs/design-docs:design-sync - Sync never-synced or stale docs/design-docs:design-link - Resolve orphaned documents
Success Criteria
A successful report:
- ✅ All design docs discovered and parsed
- ✅ Accurate metrics calculated
- ✅ Health scores computed with weighted formula
- ✅ Issues identified with severity levels
- ✅ Clear, actionable recommendations with priorities
- ✅ Proper format output (markdown/json/html)
- ✅ Insights and trends beyond raw numbers
