Skip to main content

Framework Health Dashboard Guide

Status: Active
Version: 1.0.0
Last Updated: 2026-01-03
Epic: Epic 6 - Framework Management and Maintenance
Story: Story 3 - Framework Health Monitoring
Task: E6:S03:T03 - Build framework health dashboards
Related: Framework Health Metrics, Framework Health Monitoring Procedures

Executive Summary​

This guide explains how to use the Framework Health Dashboard to visualize and monitor framework health across all AI Dev Kit frameworks. The dashboard provides comprehensive health metrics, dimension breakdowns, and actionable recommendations.

Key Features:

  • Visual Health Overview: At-a-glance health status for all frameworks
  • Detailed Reports: Comprehensive metrics for each framework
  • Dimension Analysis: Breakdown of health across six dimensions
  • Actionable Recommendations: Prioritized improvement suggestions
  • Historical Tracking: Support for trend analysis over time

Dashboard Overview​

Location​

Dashboard File: docs/framework-health/dashboard.md

Generated By: scripts/frameworks/generate-dashboard.py

Dashboard Structure​

  1. Executive Summary

    • Total frameworks analyzed
    • Average health score
    • Health status distribution

  2. Framework Health Overview Table

    • Quick comparison of all frameworks
    • Health scores and status indicators
    • Dimension scores at a glance

  3. Detailed Framework Reports

    • Individual framework analysis
    • Dimension breakdowns
    • Key metrics highlights

  4. Recommendations

    • Frameworks needing attention
    • Prioritized improvement suggestions
    • Focus areas identified

Generating the Dashboard​

Step 1: Collect Health Metrics​

First, collect health metrics for all frameworks:

# Collect metrics for all frameworks
python3 scripts/frameworks/framework-health-monitor.py \
  --output health.json \
  --report health.txt

Step 2: Generate Dashboard​

Generate the markdown dashboard from the collected metrics:

# Generate dashboard from metrics
python3 scripts/frameworks/generate-dashboard.py \
  --input health.json \
  --output docs/framework-health/dashboard.md

One-Step Generation​

You can also pipe the output directly:

# Collect and generate in one step
python3 scripts/frameworks/framework-health-monitor.py --json | \
  python3 scripts/frameworks/generate-dashboard.py \
    --output docs/framework-health/dashboard.md

Dashboard Usage​

Viewing the Dashboard​

Markdown Viewers:

  • View directly in your IDE/editor
  • Render in GitHub/GitLab
  • Convert to HTML/PDF for presentations

Web View:

  • Host on documentation site
  • Include in project documentation
  • Share with stakeholders

Interpreting Health Scores​

Health Status Levels:

  • 🟢 Excellent (≥85%): Framework is in optimal health
  • 🟡 Good (70-84%): Framework is healthy with minor improvements possible
  • 🟠 Fair (55-69%): Framework needs attention and improvements
  • 🔴 Poor (40-54%): Framework requires significant improvements
  • ⚫ Critical (<40%): Framework is in critical condition, immediate action required

Dimension Scores:

  • Each dimension (Usage & Adoption, Maintenance Activity, etc.) has its own score
  • Lower dimension scores indicate areas needing improvement
  • Focus improvements on lowest-scoring dimensions first

Using Recommendations​

Prioritization:

  1. Critical Frameworks: Address immediately (score < 40%)
  2. Poor Frameworks: Plan improvements (score 40-54%)
  3. Fair Frameworks: Schedule improvements (score 55-69%)
  4. Good Frameworks: Monitor and maintain (score 70-84%)
  5. Excellent Frameworks: Maintain current state (score ≥ 85%)

Improvement Focus:

  • Dashboard identifies lowest-scoring dimension for each framework
  • Focus improvement efforts on that dimension
  • Re-run dashboard after improvements to measure progress

Dashboard Maintenance​

Update Frequency​

Recommended Schedule:

  • Weekly: For active development periods
  • Monthly: For stable maintenance periods
  • Quarterly: For comprehensive health assessments
  • Before Releases: To ensure framework health meets thresholds

Automated Updates​

CI/CD Integration:

# Example GitHub Actions workflow
- name: Update Framework Health Dashboard
  run: |
    python3 scripts/frameworks/framework-health-monitor.py --output health.json
    python3 scripts/frameworks/generate-dashboard.py --input health.json --output docs/framework-health/dashboard.md

Cron Job:

# Weekly dashboard update
0 0 * * 0 cd /path/to/project && \
  python3 scripts/frameworks/framework-health-monitor.py --output health.json && \
  python3 scripts/frameworks/generate-dashboard.py --input health.json --output docs/framework-health/dashboard.md

Historical Tracking​

Version Control:

  • Commit dashboard updates regularly
  • Track health trends over time via git history
  • Compare dashboard versions to identify improvements/degradations

Archive Old Dashboards:

  • Keep historical dashboards for trend analysis
  • Archive monthly/quarterly dashboards
  • Use for reporting and planning

Dashboard Customization​

Custom Templates​

You can create custom dashboard templates by modifying generate-dashboard.py:

# Customize dashboard sections
# Add custom metrics
# Modify visualization format
# Include additional analysis

Framework-Specific Views​

Generate dashboards for specific frameworks:

# Single framework dashboard
python3 scripts/frameworks/framework-health-monitor.py \
  --framework kanban \
  --output kanban-health.json

python3 scripts/frameworks/generate-dashboard.py \
  --input kanban-health.json \
  --output docs/framework-health/kanban-dashboard.md

Custom Output Formats​

Extend the dashboard generator to support:

  • HTML output for web viewing
  • JSON output for API integration
  • PDF output for reports
  • CSV output for spreadsheet analysis

Integration with Workflows​

Release Workflow (RW)​

RW Step 9: Run Validators

  • Generate dashboard before release
  • Verify framework health meets thresholds
  • Include health status in release notes

Update Kanban Workflow (UKW)​

UKW Step 6: Update Kanban Board

  • Include dashboard link in board metadata
  • Reference health status in epic/story summaries
  • Track health trends in kanban documentation

Framework Update Procedures​

Pre-Update Check:

  • Review dashboard before updating frameworks
  • Identify health issues to address
  • Plan improvements as part of update

Post-Update Verification:

  • Regenerate dashboard after updates
  • Verify health maintained or improved
  • Document health changes in update notes

Troubleshooting​

Dashboard Generation Errors​

Missing Input File:

  • Ensure health metrics are collected first
  • Verify input file path is correct
  • Check JSON format is valid

Missing Output Directory:

  • Script creates directory automatically
  • Verify write permissions
  • Check disk space available

Dashboard Display Issues​

Markdown Rendering:

  • Verify markdown syntax is correct
  • Check for special characters
  • Ensure table formatting is valid

Missing Data:

  • Verify health metrics collection completed
  • Check for framework detection issues
  • Review collector module outputs

Best Practices​

Regular Monitoring​

  • Schedule: Update dashboard weekly or monthly
  • Consistency: Use same analysis period (90 days default)
  • Documentation: Document significant health changes

Action Planning​

  • Prioritize: Focus on critical and poor frameworks first
  • Track: Create tasks for health improvements
  • Measure: Track improvement progress over time

Communication​

  • Share: Include dashboard in project documentation
  • Review: Discuss health status in team meetings
  • Report: Include health metrics in status reports

References​

  • Framework Health Metrics: docs/architecture/standards-and-adrs/framework-health-metrics.md
  • Framework Health Monitoring Procedures: docs/architecture/standards-and-adrs/framework-health-monitoring-procedures.md
  • Framework Health Monitor: scripts/frameworks/framework-health-monitor.py
  • Dashboard Generator: scripts/frameworks/generate-dashboard.py
  • Epic 6: docs/project-management/kanban/epics/Epic-6/Epic-6.md
  • Story 3: docs/project-management/kanban/epics/Epic-6/Story-003-framework-health-monitoring.md

Decision Record​

Decision: Implement markdown-based dashboard with automated generation from health metrics.

Rationale:

  • Markdown is easy to read and version control
  • Automated generation ensures consistency
  • Integrates with existing documentation workflows
  • Supports historical tracking via git

Alternatives Considered:

  • Web-based dashboard (requires hosting infrastructure)
  • PDF reports (less interactive, harder to update)
  • Spreadsheet format (less readable, harder to version control)

Consequences:

  • Dashboard requires manual or automated regeneration
  • Markdown rendering depends on viewer capabilities
  • Historical tracking via git history
  • Easy to customize and extend