design-report

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:

1. Parse parameters to determine scope, format, and focus
2. Load design.config.json to identify modules and quality standards
3. Collect design documents using Glob, filtering by module and archive status
4. Parse metadata from frontmatter (status, completeness, dates, references)
5. Calculate progress metrics (overall, per-module, per-category)
6. Assess health scores using weighted formula (completeness, status, freshness, relationships)
7. Identify issues (stale docs, orphans, incomplete, sync lag, missing categories)
8. Generate report in requested format with visualizations
9. 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