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

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

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.