Agent-Skills.md

Agent Skills: Dashboard Skill

Comprehensive usage analytics and epistemic coverage dashboard across all sessions.

UncategorizedID: jongwony/epistemic-protocols/dashboard

Repository

jongwony/epistemic-protocols
jongwonyLicense: MIT
12511

Install this agent skill to your local

pnpm dlx add-skill https://github.com/jongwony/epistemic-protocols/tree/HEAD/epistemic-cooperative/skills/dashboard

Skill Files

Browse the full folder contents for dashboard.

Download Skill

Loading file tree…

epistemic-cooperative/skills/dashboard/SKILL.md

Skill Metadata

Name
dashboard
Description
"Comprehensive usage analytics and epistemic coverage dashboard across all sessions."

Dashboard Skill

Analyze all Claude Code session data to produce a comprehensive usage analytics dashboard with epistemic protocol coverage metrics, friction analysis, growth timeline, and actionable improvement recommendations.

When to Use

Invoke this skill when:

  • A user wants to see overall epistemic protocol usage metrics across all sessions
  • Evaluating protocol coverage: which situations occurred vs. which protocols were used
  • Tracking usage growth, friction patterns, and satisfaction trends over time
  • After running /onboard for deeper, full-dataset analysis

Skip when:

  • User wants protocol recommendations (use /onboard instead)
  • Quick single-protocol question (answer directly)
  • No session history exists

Workflow Overview

COLLECT → AGGREGATE → ANALYZE → PRESENT

| Phase | Owner | Tool | Decision Point | |-------|-------|------|----------------| | 1. Collect | Main | Glob | Inventory + path decision | | 2. Aggregate | Subagent (coverage-scanner) | Bash, Read, Grep, Glob | Batch data collection | | 3. Analyze | Main | — | 7 computations | | 4. Present | Main | Write, Bash | HTML dashboard + console summary |

Data Sources

Primary: Usage Data Cache

| Source | Method | Extracts | |--------|--------|----------| | ~/.claude/usage-data/facets/{session_id}.json | Glob + Read | friction_counts, friction_detail, goal_categories, session_type, outcome, user_satisfaction_counts | | ~/.claude/usage-data/session-meta/{session_id}.json | Glob + Read | tool_counts, git_commits, git_pushes, languages, duration_minutes, start_time, first_prompt |

Secondary: Session Logs

| Source | Method | Extracts | |--------|--------|----------| | ~/.claude/projects/*/*.jsonl | Glob | All session JSONL files on disk | | Session JSONL files | Grep command-name + "skill":" | Protocol usage history (slash commands + Skill tool invocations) |

Phase Execution

Phase 1: Collect (Main)

  1. Glob ~/.claude/usage-data/facets/*.json → inventory facets files
  2. Glob ~/.claude/usage-data/session-meta/*.json → inventory session-meta files
  3. Note JSONL glob pattern ~/.claude/projects/*/*.jsonl (scanner runs glob internally)
  4. Intersect facets ∩ session-meta by filename stem (session_id)
  5. Path decision: facets ∩ session-meta ≥ 10 → Path A, else Path B

If no facets or session-meta data found: report "No usage data available. Run some Claude Code sessions first, then try /dashboard again." and stop.

Phase 2: Aggregate (Subagent: coverage-scanner)

Call coverage-scanner subagent with:

  • facets_dir: ~/.claude/usage-data/facets/
  • session_meta_dir: ~/.claude/usage-data/session-meta/
  • session_jsonl_glob: ~/.claude/projects/*/*.jsonl (scanner runs glob + grep internally, avoiding 900+ paths in prompt)
  • mode: "path_a" or "path_b" based on Phase 1 decision

The subagent returns aggregated data: friction totals, outcome/satisfaction distributions, tool totals, timeline, protocol usage (slash commands + Skill tool invocations, de-duplicated), gate interaction data (per-protocol gated/relay counts), code change statistics.

Phase 3: Analyze (Main) — 9 Computations

3.1 Coverage Computation

For each protocol, determine:

  • situation_occurred: whether the deficit situation was detected in session data
  • situation_used: whether the protocol's slash command was actually used

| Protocol | situation_occurred (Path A) | situation_occurred (Path B) | |----------|---------------------------|---------------------------| | Syneidesis | friction wrong_approach OR friction excessive_changes OR rework | rework + high exploration | | Aitesis | friction context_loss | N/A | | Prosoche | friction wrong_file_edited | deploy/push keywords | | Prothesis | — | exploration ratio ≥ 3:1 | | Katalepsis | — | verification firstPrompt | | Epharmoge | — | N/A (conditional protocol) |

situation_used detection: From Phase 2 Protocol Usage output (coverage-scanner detects via slash commands and Skill tool invocations in a single pass, de-duplicated per session). The scanner owns the mapping from skill names to protocol names — see coverage-scanner.md step 2c for the canonical mapping table.

Coverage ratio per protocol: situation_used / situation_occurred. Protocols with no detected situations = N/A.

3.2 Protocol Usage

Count protocol invocations per protocol from Phase 2 aggregated data (merged from slash commands + Skill tool). Include first usage date, detection method breakdown (command vs Skill tool), and session count if available.

3.3 Friction Mapping

Aggregate friction_counts from Phase 2. Map to protocol groups using the Tertiary Mapping Table:

| Friction Key | Protocol Group | |---|---| | wrong_approach | Syneidesis | | excessive_changes | Syneidesis | | context_loss | Aitesis | | wrong_file_edited | Prosoche | | Others (buggy_code, api_errors, etc.) | Environmental (no protocol mapping) |

3.4 Growth Timeline

From Phase 2 timeline data:

  • Weekly session counts
  • Protocol adoption dates (first slash command usage per protocol)
  • Cumulative session trend

3.5 Achievements

Compute milestones:

  • Session milestones: 10, 50, 100, 250, 500 sessions
  • Protocol milestones: first protocol used, 3+ protocols used, all core protocols used
  • Code milestones: 100 commits, 500 commits
  • Streak: consecutive days with sessions (from timeline data)

3.6 Satisfaction Score

From user_satisfaction_counts (Path A only):

  • Weighted average on 0-100 scale
  • Split into first-half / second-half trend comparison

3.7 Quality Score

Composite score (0-100):

  • Outcome (35%): success ratio from outcome distribution
  • Friction rate (20%): inverse of friction per session
  • Satisfaction (25%): weighted satisfaction score
  • Coverage (20%): average coverage ratio across applicable protocols

3.8 Gate Efficiency

From Phase 2 gate interaction scan:

  • Per-protocol: gated_interactions / total_gates ratio
  • Cross-session average gate efficiency

| Protocol | Avg Gate Efficiency | Relay Gates | Gated Gates | Total Sessions | |----------|--------------------:|------------:|------------:|---------------:|

Gate efficiency = 1.0 means all gates user-facing. Lower values indicate more automation via relay classification.

3.9 Relay Erosion

For protocols with 3+ session history:

  • Track relay→gated transitions (erosion: gates that were auto-resolved becoming user-gated)
  • Track gated→relay transitions (stabilization: gates becoming auto-resolvable with experience)
  • If insufficient data (protocol used < 3 sessions): report "Insufficient data for erosion tracking."

Phase 4: Present (Main)

  1. HTML Dashboard:

    • Pre-write step: call Bash mkdir -p ~/.claude/.dashboard to ensure the parent directory exists (handles fresh environments without prior .dashboard/ activity)
    • Write to ~/.claude/.dashboard/dashboard.html via Write tool
    • Refer to references/html-template.md for the full HTML skeleton
    • 11 sections: Coverage, Protocol Usage, Friction→Protocol, Improvement Opportunities, Growth Timeline, Achievements, Satisfaction Trends, Quality Score, Gate Efficiency, Relay Erosion, Quick Actions
    • Path B degradation: Sections 3 (Friction), 7 (Satisfaction), 8 (Quality Score), 9 (Gate Efficiency), 10 (Relay Erosion) show "Facets data enables richer analysis" guidance. Sections 9-10 additionally show "Insufficient data for erosion tracking" when protocol session count < 3

  2. Console Summary: Output key metrics:

    • Total sessions analyzed
    • Coverage summary (X/Y protocols with situations detected)
    • Top friction areas
    • Quality score (if available)
    • File path: ~/.claude/.dashboard/dashboard.html

  3. Open in browser: Call Bash open ~/.claude/.dashboard/dashboard.html to launch the dashboard in the default browser

HTML Artifact Guidelines

Refer to references/html-template.md for the full HTML skeleton, CSS classes, and detailed artifact guidelines.

Rules

  1. Privacy: Never transmit session data externally. All analysis runs locally.
  2. Raw data in subagent: coverage-scanner subagent returns raw aggregated data only — all computation, mapping, and scoring happen in the main agent.
  3. Evidence-based metrics: Every metric must be derived from actual data. No estimated or interpolated values.
  4. Graceful degradation: Path B produces useful output without facets data. Sections requiring facets show clear guidance to obtain richer data.
  5. Idempotent: Running /dashboard multiple times produces updated results. Previous dashboard is overwritten.
  6. Subagent delegation: Phase 2 batch aggregation MUST be delegated to coverage-scanner subagent (single). Main agent handles Phases 1, 3, 4.
  7. No protocol recommendations: /dashboard provides analytics only. For protocol recommendations, direct users to /onboard.