Report

---
name: report
description: "Generate Growth Map (epistemic profile + insights integration) from session patterns and workflow data."
---

# 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)

Paths below written `{config_dir}/…` take `{config_dir}` = `CLAUDE_CONFIG_DIR` when set, else `~/.claude`. Resolve it ONCE per invocation with Bash `printf '%s\n' "${CLAUDE_CONFIG_DIR-$HOME/.claude}"` and substitute the absolute result before any Read/Glob/Grep call.

| Source | Method | Extracts |
|--------|--------|----------|
| `{config_dir}/CLAUDE.md` | Read | Workflow style keywords (team, delegation, safety) |
| `{config_dir}/rules/` | Glob | Rule file presence (which domains are rule-governed) |
| `{config_dir}/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 |
|--------|--------|----------|
| `{config_dir}/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 |
| `{config_dir}/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 |
|--------|--------|----------|
| `{config_dir}/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 `{config_dir}/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: `{config_dir}/CLAUDE.md`, `{config_dir}/rules/`, `{config_dir}/settings.json`, MEMORY.md

**Insights detection** (main agent, concurrent with project-scanner — no dependency on subagent output):
1. Glob `{config_dir}/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 `{config_dir}/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 `{config_dir}/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 slash command history
   **Path B** (facets-absent, per project):
   a. **Call session-analyzer subagent** in **full mode** (one per project):
      - Subagent receives session JSONL file paths
      - Subagent extracts: tool frequencies, rework indicators (same file 3+ edits), slash command history, Bash keywords, AskUserQuestion presence, context snippets, situation co-occurrence facts, conversation quality signals
      - Subagent returns structured analysis (raw data only, no interpretation)
4. Main agent analyzes `firstPrompt` text from `sessions-index.json` for ambiguity/exploration keywords:
   - Vague starts: `improve`, `optimize`, `something like`
   - Ideation asks: `ideas for`, `brainstorm` and Korean equivalents
   - Vague starts (Korean equivalents): expressions meaning "I want to~", "how do I~", "a bit more", "enhance"
   - Exploratory framing: `explore`, `investigate`, `look into` and Korean equivalents
5. Main agent uses secondary sources from Phase 1 project-scanner output:
   - `{config_dir}/CLAUDE.md`: keywords indicating team work, delegation preferences, safety focus
   - `{config_dir}/rules/`: which domains have explicit rules (communication, boundaries, etc.)
   - `{config_dir}/settings.json`: hook configurations (safety consciousness indicator)
   - MEMORY.md: existing patterns and insights

### Phase 3: Map (Protocol Matching)

Apply the mapping tables below to match observed patterns to protocols.

1. Match each behavioral pattern against the Primary Mapping Table
2. Classify match strength:
   - **Strong**: Pattern observed in 3+ sessions
   - **Weak**: Pattern observed in 1-2 sessions
   - **None**: Pattern not observed
3. Match environmental patterns against the Secondary Mapping Table
3.5. Match friction patterns against the Tertiary Mapping Table (Path A projects only)
   - Aggregate friction_counts across sessions per project
   - Map Primary-type keys to protocols
   - Combine with Primary/Secondary match strengths (additive, Weak+friction=Strong)
4. Determine Fallback Tier:
   - **Tier 1**: 3+ strong patterns found — map precisely to observed patterns
   - **Tier 2**: 1-2 weak patterns found — map + supplementary recommendations
   - **Tier 3**: No patterns / new user — Starter Trio recommendation
5. Select final 3-5 protocol recommendations
6. **Session Diagnostics**: Merge situation co-occurrence facts from Phase 2 subagent output (tool-usage patterns) with main agent firstPrompt analysis (Katalepsis verification situations). Then determine protocol mapping and cross-reference with slash command history:
   - Situations where a protocol was applicable but not used → anti-pattern candidates
   - Conversation quality signals (user corrections, backtracking) from Phase 2 subagent Step 2.7 → conversation anti-patterns
   - Each anti-pattern: describe the situation, reference the snippet, suggest the protocol

### Phase 4: Present (Growth Map Artifact)

1. Present analysis summary via gate interaction:
   - Number of sessions analyzed, projects scanned
   - Key patterns discovered (with evidence counts)
   - Proposed protocol recommendations
   - Growth Map path: **A** (insights available) or **B** (insights absent)
   - Ask user to confirm before generating artifact

2. On confirmation, generate Growth Map HTML artifact via Write tool:
   - Save to `{config_dir}/.report/growth-map.html`
   - Structure varies by `growth_map_path`:

   **Path A — Growth Map (insights as targeting input, epistemic-lens output)**:

   Architecture: 2-Pass Compiler. insights = 1st pass (behavioral sweep), report = 2nd pass (epistemic resolution). Each section uses insights data as **input** to generate analysis insights **cannot produce** — protocol adoption patterns, epistemic coverage gaps, deficit detection.

   | # | Section | Insights Input (targeting) | Report Output (orthogonal) |
   |---|---------|---------------------------|---------------------------|
   | ① | Epistemic Snapshot | `at_a_glance` (context) | Protocol coverage delta: which decision types are structured vs unstructured. Gap between friction frequency and protocol adoption |
   | ② | Epistemic Profile | `interaction_style` (baseline) | Protocol adoption trajectory: which protocols used when, adoption curve over time, preference patterns (planning vs verification vs execution) |
   | ③ | Protocol Impact | `what_works` (positive-session targets) | Cases where protocol usage correlated with better outcomes: protocol-present sessions vs protocol-absent sessions with similar goals |
   | ④ | Growth Opportunities | `friction_analysis` + `suggestions` | Anti-patterns (protocol applicable but absent) + dual-layer resolution cards |
   | ⑥ | Recommendations + Install | Report mapping tables | Protocol recommendations + install commands + batch install |
   | ⑦ | Next Protocols | `on_the_horizon` (context) | Protocol adoption path: which protocols to learn next based on work trajectory + epistemic gap analysis |

   Note: ⑤ Coverage is reserved for Phase 2 (dashboard absorption). Uses `project_areas` from Quaternary + coverage-scanner data.

   **④ Growth Opportunities — dual-layer cards**:
   Each friction item as a card with two resolution layers:
   - **Execution layer** (tag: Execution): CLAUDE.md rule or configuration suggestion (behavioral fix) — sourced from insights `suggestions`
   - **Epistemic layer** (tag: Epistemic): Protocol `/command` CTA (structural fix) — sourced from report anti-pattern analysis
   - **Evidence**: Session snippet or friction_detail narrative + resume command
   - Source: Tertiary Mapping Table (friction → protocol) + Quaternary Mapping Table (suggestions → execution layer)

   **Path B — Epistemic Profile (report-only fallback)**:
   - ④ renders with existing anti-pattern cards (diagnostics + patterns)
   - ⑥ renders with existing recommendation cards + batch install + quick start
   - ①②③⑦ replaced by CTA card: "Run `/insights` first for a richer Growth Map"

   Refer to `references/html-template.md` for the HTML skeleton, CSS classes, and section templates.

3. Open HTML artifact in default browser via Bash: `cfg="${CLAUDE_CONFIG_DIR-$HOME/.claude}"; open "${cfg:+$cfg/}.report/growth-map.html"`

### Phase 5: Guide (Trial CTA + Install Helper)

1. **Check plugin installation**: verify whether recommended protocols are installed
   - Check plugin installation via file existence: Glob for `{config_dir}/plugins/cache/epistemic-protocols/{plugin-name}/*/skills/*/SKILL.md`. If found, the protocol is installed.
   - If installed: provide direct CTA (e.g., "Try `/gap` right now in your current session")
   - If not installed: guide marketplace installation:
     - `claude plugin install epistemic-protocols/{plugin-name}` or marketplace URL
     - Brief installation steps
     - If 2+ protocols not installed: also mention batch install script (`scripts/install.sh`)

2. Present a **concrete usage scenario** for the top recommendation:
   - Based on the user's actual work context (derived from session analysis)
   - Example: "You edited the same file 5 times in recent sessions — running `/gap` before committing can surface blind spots that drive rework"

3. Close with: "Refer to the HTML profile for remaining recommendations. You can re-run `/report` anytime for updated analysis."

## Pattern to Protocol Mapping

### Primary Mapping Table (Behavioral Patterns)

| Observable Pattern | Detection Method | Protocol | Rationale |
|---|---|---|---|
| Same file edited 3+ times | Edit path frequency | **Syneidesis** `/gap` | Repeated edits without prior gap check |
| Exploration ratio 3:1+ across multiple sessions | (Read+Grep+Glob) / (Edit+Write) threshold | **Prothesis** `/frame` | Sustained exploration without analytical framework |
| Vague first prompts ("improve", "optimize") | firstPrompt keyword match: short underspecified directives | **Euporia** `/elicit` | Goal coordinate aporia — reverse-induce endpoint from substrate |
| Ideation-shaped first prompts ("ideas for", "brainstorm") | firstPrompt keyword match: ideation asks | **Heuresis** `/ideate` | Candidate field underexpanded — frame-parallel divergence before any selection |
| Comprehension-signal keywords in firstPrompt (user-authored text only) | firstPrompt keyword match: "explain", "what did you do", "help me understand", "don't understand", "can't follow", "verify", "check" | **Katalepsis** `/grasp` | Comprehension of a result is not established — the user either assumes it and wants it checked, or already knows it is absent |

**Merismos excluded by design**: `/apportion`'s deficit is `¬condition_bearing(G)` — whether a goal already carries units whose completion conditions are settled. No observable available to this skill (firstPrompt keywords, a configured stop-hook) can establish that negative; each only detects that an autonomous interval is *intended*, which is equally true of a goal that is already condition-bearing. A row built on either observable therefore cannot honestly claim a deficit match at any strength, so none is carried here — matching `dashboard/SKILL.md`'s coverage table, which marks Merismos `N/A` for the identical reason. `/apportion` stays discoverable through `/catalog` and `/onboard`, neither of which claims deficit detection.

### Secondary Mapping Table (Environment Patterns)

No environment pattern currently clears the accuracy bar for a protocol match (a stop-hook/completion-enforcer configuration was previously mapped to Merismos here; removed for the same reason as above — hook presence alone cannot establish `¬condition_bearing(G)`). Reserved for a future observable that can establish a deficit rather than merely a correlated setup step.

### Tertiary Mapping Table (Friction Patterns — from Facets)

Applied only when facets data is available (Path A). Complements Primary and Secondary — does not replace them.

| Friction Key | Protocol | Rationale | Signal Type |
|---|---|---|---|
| `wrong_approach` | **Syneidesis** `/gap` | Approach gap undetected | Primary |
| `wrong_approach` + rework situation | **Syneidesis** `/gap` | Approach gap undetected, accompanied by rework | Primary |
| `excessive_changes` | **Syneidesis** `/gap` | Scope boundary gap undetected | Primary |
| `context_loss` | **Aitesis** `/inquire` | Information loss due to insufficient context | Primary |
| `wrong_file_edited` | **Syneidesis** `/gap` | Scope boundary gap undetected — the edit landed outside intent | Primary |
| `buggy_code`, `api_errors`/`api_error`, `tool_errors`/`tool_error`/`tool_failure`/`tool_limitation`, `external_blocker`/`external_dependency`, `merge_conflict`, `minor_correction`, `excessive_verification`/`excessive_tool_calls`, `unrelated_environment_issue`/`deployment_gap`, `agent_*` | — | Infrastructure/environment friction — not epistemic deficit | Environmental |

**Signal Type**: Primary = directly maps to protocol deficit. Environmental = reported only (no mapping).
**Interaction**: friction Primary signals are additive with existing Primary/Secondary signals. Same-protocol evidence escalates strength (Weak+friction=Strong).
**Co-change**: friction keys must be synchronized with `agents/session-analyzer.md` Targeted Step Tier 2 behavioral proxies.

Composition rules (protocol chaining based on pattern combinations) are deferred to a future version.

### Quaternary Mapping Table (Derived Metrics — from Insights)

Applied only when `growth_map_path = A`. Friction-to-protocol mapping uses the Tertiary table (unchanged). This table maps non-friction insights signals as targeting inputs for Growth Map ④ Growth Opportunities dual-layer cards.

| Metric | Signal | Protocol | Rationale |
|--------|--------|----------|-----------|
| `suggestions.usage_patterns` | behavioral recommendation | — (execution layer) | CLAUDE.md / config suggestion |
| `suggestions.features_to_try` | tool adoption gap | — (execution layer) | Feature utilization improvement |
| session_type = exploration (high ratio) | framework absence | Prothesis | Sustained exploration without analytical framework |
| user_satisfaction low sessions | deep-dive target | — (priority signal) | Protocol absence in dissatisfied sessions |
| response_time long segments | deliberation point | — (priority signal) | Epistemic deficit candidate |

## Fallback Strategy

**Tier 1** (3+ strong patterns): Map precisely to observed patterns.

**Tier 2** (1-2 weak patterns): Map observed patterns + add supplementary "also useful in these situations" recommendations.

**Tier 3** (No patterns / new user): Recommend the **Starter Trio** — three universally applicable protocols:
- **Syneidesis** `/gap` — When you want to check for blind spots before deciding
- **Aitesis** `/inquire` — When execution context feels insufficient
- **Horismos** `/bound` — When ownership of multi-domain decisions is unclear

Selection rationale: covers the three most common entry points — decision auditing, context grounding, and boundary definition. Low entry barrier, independently usable.

## Also Available

Aitesis is pattern-matched via the Tertiary Mapping Table (`context_loss` friction key, Path A only). The following protocol is not yet pattern-matched and remains available for manual invocation:

- **Epharmoge** `/contextualize` — Detect application-context mismatch after execution. Use when correct output may not fit the actual deployment context.

Epharmoge will be integrated into pattern-based detection in a future version as reliable detection heuristics are developed.

## 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 and co-occurrence facts in subagents**: session-analyzer subagents return raw counts, co-occurrence facts, and conversation quality signals — situation-to-protocol mapping happens in the main agent only.
3. **Evidence-based recommendations**: Every protocol recommendation must cite at least one observable pattern with data. Tier 3 fallback explicitly states "insufficient data for personalized recommendation."
4. **No auto-install**: Guide installation but never install plugins automatically. CTA = user action.
5. **Idempotent**: Running `/report` multiple times produces updated results based on latest data. Previous artifacts are overwritten.
6. **Session file access**: Access session JSONL files via Grep pattern matching or targeted Read with offset/limit (for efficiency). Never Read entire JSONL files — they can be very large.
7. **Subagent delegation**: Phase 1 project scanning MUST be delegated to project-scanner subagent (single). Phase 2 session analysis: Path A (facets-available) delegates to session-analyzer in targeted mode; Path B (facets-absent) delegates in full mode. Maximum 3 parallel subagents across both paths.
8. **Facets as accelerator**: Facets data is a pure accelerator — its absence must not degrade output quality. Path B produces output quality at least equal to the pre-enhancement baseline; new capabilities (co-occurrence detection, quality signals) are available in both paths.
9. **Best-effort parsing**: report.html parsing is best-effort. Parse failure triggers automatic `growth_map_path = B` fallback, not an error. HTML structure changes are expected — minimize CSS class/ID dependency.
10. **Insights as targeting input**: When `growth_map_path = A`, use insights' LLM-analyzed data as targeting input — do not re-analyze raw sessions for what insights already processed (token efficiency). Generate orthogonal epistemic analysis: insights identifies WHAT happened (behavioral narrative), report analyzes WHICH epistemic structures were absent (protocol-lens). Transform the insights narrative into protocol adoption analysis, coverage gap detection, and anti-pattern identification.