dashboard

What this skill does

# 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 8 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,