perf-dashboard

name	perf-dashboard
description	Generate an interactive local HTML dashboard from Firebase Performance query results. Shows worst-performing screens, highest-volume screens, and 30-day trends with Chart.js. TRIGGER when: user asks for a dashboard, visualization, chart, report, HTML output, "show me the results", or "open dashboard" after running /perf-query. SKIP if: user hasn't run /perf-query yet (no .perf/data/ exists), or if they're asking to fetch new data (use /perf-query) or fix a screen (use /perf-fix).
allowed-tools	Bash, Read, Write

Firebase Performance Dashboard

Generate a self-contained HTML dashboard from BigQuery performance data. This skill uses a helper script for deterministic template assembly.

IMPORTANT: Autonomous Execution

Run all steps without asking for confirmation. Verify data, assemble dashboard, open in browser, and print summary — all in one go. Only pause if data files are missing (tell the user to run /perf-query first). Do NOT ask "Ready to proceed?" or "Should I open the dashboard?"

Step 1: Verify Data Exists

Check that these files exist:

• .perf/config.json
• .perf/data/screen_summary.json
• .perf/data/app_daily_trend.json
• .perf/data/query_metadata.json

If any are missing, STOP: "Query data not found. Run /perf-query first."

Step 2: Assemble Dashboard

Locate and run the assembly script. Check these paths in order:

• .claude/skills/perf-dashboard/scripts/assemble_dashboard.sh
• skills/perf-dashboard/scripts/assemble_dashboard.sh

bash {script_path}/assemble_dashboard.sh .

The script:

1. Reads all data JSON files from .perf/data/
2. Reads the dashboard-template.html from its own skill directory
3. Injects the data into template placeholders
4. Writes .perf/dashboard.html
5. Auto-opens in the default browser

If the script is not found, assemble the dashboard manually:

1. Read the dashboard-template.html from the skill directory
2. Replace {{SCREEN_SUMMARY_JSON}} with contents of .perf/data/screen_summary.json
3. Replace {{SCREEN_DAILY_JSON}} with contents of .perf/data/screen_daily.json (or [] if missing)
4. Replace {{APP_TREND_JSON}} with contents of .perf/data/app_daily_trend.json
5. Replace {{QUERY_METADATA_JSON}} with contents of .perf/data/query_metadata.json
6. Replace {{APP_ID}}, {{PLATFORM}}, {{TABLE_NAME}} from .perf/config.json
7. Replace {{GENERATED_AT}} with current ISO timestamp
8. Write to .perf/dashboard.html

Step 3: Open in Browser

If the script didn't auto-open, open manually:

if [[ "$OSTYPE" == "darwin"* ]]; then open .perf/dashboard.html
elif [[ "$OSTYPE" == "linux"* ]]; then xdg-open .perf/dashboard.html 2>/dev/null
elif [[ "$OSTYPE" == "msys"* || "$OSTYPE" == "cygwin"* ]]; then explorer.exe .perf/dashboard.html 2>/dev/null
else echo "Open .perf/dashboard.html in your browser"
fi

Step 4: Print Summary

Read .perf/data/screen_summary.json. Each row has fields: screen_name, frozen_frames_pct, slow_render_pct, total_samples, plus a daily breakdown. Numeric fields come back as strings — cast with float() before arithmetic.

Rank the top 5 worst screens by composite score (frozen * 0.6 + slow * 0.4). For "highest volume," sort descending on total_samples.

Dashboard generated at .perf/dashboard.html

Quick stats:
- {N} screens analyzed
- Worst screen: {name} (frozen: {X}%, slow: {Y}%)
- Highest volume: {name} ({N} samples)
- 30-day trend: frozen {direction}, slow render {direction}

Top 5 worst performing:
  1. {name} — frozen: {X}%, slow: {Y}%
  2. {name} — frozen: {X}%, slow: {Y}%
  3. {name} — frozen: {X}%, slow: {Y}%
  4. {name} — frozen: {X}%, slow: {Y}%
  5. {name} — frozen: {X}%, slow: {Y}%

That's it — this is the end of the main workflow. If the developer wants to go further and fix issues in the code, they can run /perf-fix {worst screen name} as an optional next step. Do not suggest this unless they ask — the dashboard is the deliverable.

Error Handling

Error	Action
Data files missing	"Run /perf-query first to fetch performance data."
Template not found	"Dashboard template not found. Reinstall the perf-dashboard skill."
python3 not available	"Python 3 is required for dashboard assembly. Install from python.org."
Browser open fails	"Dashboard saved to .perf/dashboard.html — open it manually in your browser."
Empty screen summary	"No screen data to display. Run /perf-query to refresh."