Agent Skills: Report Skill

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 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:
   • ~/.claude/CLAUDE.md: keywords indicating team work, delegation preferences, safety focus
   • ~/.claude/rules/: which domains have explicit rules (communication, boundaries, etc.)
   • ~/.claude/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 ~/.claude/.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: open ~/.claude/.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 ~/.claude/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 | | Bash contains deploy/push/apply keywords | Bash input keyword match | Prosoche /attend | Risky execution without compiled guardrail conditions | | 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 | | Verification keywords in firstPrompt (user-authored text only) | firstPrompt keyword match: "explain", "what did you do", "help me understand", "verify", "check" | Katalepsis /grasp | Need to verify comprehension of results |

Secondary Mapping Table (Environment Patterns)

| Observable Pattern | Source | Protocol | Rationale | |---|---|---|---| | Many hook configurations | settings.json hooks | Prosoche /attend (reinforcing) | User already values safety mechanisms |

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 | Prosoche /attend | Execution boundaries not compiled into verifiable conditions | 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.