report

What this skill does

# Report Skill

Generate a Growth Map from a user's Claude Code sessions — integrating `/insights` data with session analysis for protocol recommendations with dual-layer resolution (execution + epistemic). Falls back to Epistemic Profile when insights data is unavailable.

## When to Use

Invoke this skill when:
- Analyzing session patterns to identify protocol recommendation evidence
- Generating a Growth Map (integrating insights + session analysis)
- Re-evaluating protocol adoption based on updated session data

Skip when:
- User wants hands-on protocol learning (use /onboard)
- User already knows which protocol to use (direct invocation)
- No session history exists and user prefers manual exploration
- Quick single-protocol question (answer directly)

## Workflow Overview

```
SCAN → EXTRACT → MAP → PRESENT → GUIDE
```

| Phase | Owner | Tool | Decision Point |
|-------|-------|------|----------------|
| 1. Scan | Subagent + Main | Bash, Read, Glob | Project discovery + insights detection |
| 2. Extract | Subagent (session-analyzer) | Grep, Read | Pattern extraction from JSONL |
| 3. Map | Main | — | Pattern → Protocol matching |
| 4. Present | Main | Gate, Write, Bash | User confirmation + Growth Map HTML |
| 5. Guide | Main | Gate | Protocol trial CTA |

## Data Sources

### Primary: Session Logs (Behavioral Patterns)

| Source | Method | Extracts |
|--------|--------|----------|
| `sessions-index.json` (recent 3 projects) | Read | firstPrompt (start patterns), summary (result patterns), messageCount (conversation length) |
| Session JSONL (up to 3 per project) | Grep `"tool_use"` | Tool usage frequency distribution (Edit/Read/Bash/AskUserQuestion ratios) |
| Session JSONL | Grep `command-name` | Slash command history (existing protocol usage) |
| Session JSONL | Grep `"Bash"` + keywords | Execution patterns (deploy, push, test, install frequency) |
| Session JSONL (pattern evidence) | Grep (context) + Read (offset/limit) | Context snippets: (user message, AI response) pairs near pattern evidence |

### Secondary: Configuration (Environment Context)

| Source | Method | Extracts |
|--------|--------|----------|
| `~/.claude/CLAUDE.md` | Read | Workflow style keywords (team, delegation, safety) |
| `~/.claude/rules/` | Glob | Rule file presence (which domains are rule-governed) |
| `~/.claude/settings.json` | Read (hooks only) | Hook usage patterns |
| MEMORY.md (if exists) | Read | Existing insights, recurring patterns |

### Tertiary: Usage Data Cache (Accelerator — Optional)

| Source | Method | Extracts |
|--------|--------|----------|
| `~/.claude/usage-data/facets/{session_id}.json` | Read | friction_counts, friction_detail, goal_categories, session_type, outcome, user_satisfaction_counts, brief_summary, underlying_goal, primary_success, claude_helpfulness |
| `~/.claude/usage-data/session-meta/{session_id}.json` | Read | tool_counts, git_commits, git_pushes, languages, uses_task_agent, duration_minutes, first_prompt, user_response_times, message_hours |

**Join key**: session_id from sessions-index.json matches filename in both directories.
**Availability**: Only exists if user has run `/insights` (built-in command). Read-only consumption — never write to these caches.

### Quaternary: Insights Report (Growth Map Accelerator — Optional)

| Source | Method | Extracts |
|--------|--------|----------|
| `~/.claude/usage-data/report.html` | Read + best-effort parsing | at_a_glance, interaction_style, what_works, friction_analysis, suggestions, on_the_horizon, project_areas |

**Availability**: Only exists after `/insights` execution. Enables Growth Map Path A (epistemic-lens analysis using insights as targeting input). Parsing is best-effort — HTML structure changes trigger graceful fallback to Epistemic Profile mode.
**Relationship**: insights = 1st pass (behavioral sweep), report = 2nd pass (epistemic resolution). Report consumes insights' analyzed data as input, not output — generates orthogonal epistemic analysis that insights cannot produce.
**Independence**: `growth_map_path` (A/B from insights availability) is orthogonal to Phase 2 Path A/B (facets availability per project). Growth Map path controls analysis depth; facets path controls extraction method.

## Phase Execution

### Phase 1: Scan (Project Discovery) — Subagent Delegated

**Call project-scanner subagent** to handle all project discovery. Phase 1 inherently requires 5+ Bash calls (directory listing, stat, file reads), always exceeding the delegation threshold. Pre-planned delegation avoids reactive interruption.

The subagent:
1. Lists project directories under `~/.claude/projects/`
2. Selects the 3 most recently modified projects (using `stat` for modification time)
3. Reconstructs actual project paths from encoded directory names (e.g., `-Users-choi-myproject` → `~/myproject`). Records project path ↔ session mapping for Phase 4 resume commands
4. Reads each project's `sessions-index.json`
5. Aggregates: total session count, average/max messageCount, last activity date
6. Scans secondary sources: `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/settings.json`, MEMORY.md

**Insights detection** (main agent, concurrent with project-scanner — no dependency on subagent output):
1. Glob `~/.claude/usage-data/report.html` — existence check
2. If present: Grep report.html for section-identifying patterns (heading text, `id=` attributes), then Read with offset/limit per section. Never Read entire file if >500 lines.
   - Success → set `growth_map_path = A`, store extracted sections as targeting inputs for epistemic-lens analysis
   - Parse failure → set `growth_map_path = B` (graceful degradation, no error)
3. If absent: set `growth_map_path = B`

Main agent awaits both project-scanner output and insights detection, then proceeds to Phase 2.

**Edge cases**:
- If `~/.claude/projects/` does not exist or is empty: subagent reports absence (secondary sources still scanned), main agent skips Phase 2 extraction (steps 1-3), proceeds to Phase 2 step 5 (secondary sources from Phase 1 output) and Phase 3, set Tier 3
- If `sessions-index.json` cannot be parsed (corrupted JSON): subagent skips that project, continues with remaining
- Project path reconstruction: directory names encode absolute paths with `/` and `.` replaced by `-`. Subagent uses heuristics (home directory prefix, known directory structure) to reconstruct readable `~/...` paths

If no `sessions-index.json` found in any project, skip Phase 2 extraction (steps 1-3), proceed to Phase 2 step 5 (secondary sources from Phase 1 output) and Phase 3, set fallback tier to Tier 3.

### Phase 2: Extract (Pattern Extraction) — Dual-Path

1. Use session JSONL paths from Phase 1 project-scanner output (3 most recently modified sessions per project, maximum 9 total).
2. **Facets availability check**: Glob `~/.claude/usage-data/facets/*.json` once, intersect returned filenames (stem = session_id) with selected session IDs. Determine path per project:
   - **Path A**: 2+ sessions in the project have facets files → facets-accelerated extraction
   - **Path B**: 0-1 sessions have facets → full subagent extraction (baseline)
3. **Path A** (facets-available, per project):
   a. Read all facets + session-meta JSON files for the project in parallel (up to 6 reads per project, independent; across multiple Path A projects, reads also run in parallel) → aggregate friction_counts, collect non-empty friction_detail (max 3), aggregate goal_categories/session_type/outcome/user_satisfaction_counts, collect underlying_goal/primary_success/claude_helpfulness
   b. From session-meta: sum tool_counts, git_commits/git_pushes, languages, collect user_response_times/message_hours (replaces behavioral pattern extraction)
   c. For top 2-3 friction keys with friction_detail: call session-analyzer in **targeted mode** (friction_pointers) for snippet extraction only
   d. Co-occurrence facts: derive situations from goal_categories + check firstPrompt for sla