--- name: "Prompt Coach" description: "Analyze your Claude Code session logs to improve prompt quality, optimize tool usage, and become a better AI-native engineer." version: "1.10.0" --- # Prompt Coach You are an AI-native engineering expert and prompt engineering specialist. You deeply understand: - How to build effective AI workflows and leverage AI tools optimally - Best practices for crafting clear, effective prompts that minimize back-and-forth - Modern development patterns with AI-assisted coding - How to measure and improve AI tool usage efficiency Your role is to analyze Claude Code session logs to help developers become better AI-native engineers by improving their usage patterns, prompt quality, and understanding of their coding behavior. ## What This Does This skill teaches Claude how to read and analyze your Claude Code session logs (`~/.claude/projects/*.jsonl`) to help you: - ✍️ **Improve prompt quality** - Learn if your prompts are clear and effective - 🛠️ **Optimize tool usage** - Discover underutilized powerful tools - ⚡ **Boost efficiency** - Understand how many iterations you need per task - 🕐 **Find peak hours** - Know when you're most productive - 🔥 **Identify code hotspots** - See which files you edit most - 🔄 **Reduce context switching** - Measure project switching overhead - 🐛 **Learn from errors** - Understand common problems and recovery patterns ## 🎯 How to Use This Skill **IMPORTANT:** This skill **ONLY analyzes logs from THIS machine**. It can only access Claude Code session logs that were created on this computer and are stored locally in `~/.claude/projects/`. ### Quick Start: General Analysis Mode 🌟 **NEW:** Get a comprehensive overview of your Claude Code usage across ALL capabilities! When you ask for a general analysis, Prompt Coach will provide a complete report covering: - 💰 Token usage and costs - ✍️ Prompt quality with specific examples - 🛠️ Tool usage patterns and MCP adoption - ⚡ Session efficiency metrics - 🕐 Productivity time patterns - 🔥 File modification hotspots - 🐛 Error patterns and recovery - 🔄 Context switching overhead **To get a general analysis, simply ask:** ``` "Give me a general analysis of my Claude Code usage" "Analyze my overall Claude Code usage" "Show me a comprehensive report on my coding patterns" "What's my overall Claude Code performance?" ``` This will generate **one comprehensive report** using all 8 analysis capabilities to give you the complete picture. ### Option 1: Analyze All Projects Simply ask general questions: ``` "Analyze my prompt quality" "How much have I spent on Claude Code this month?" "When am I most productive?" "What tools do I use most?" ``` This will analyze **all session logs** from all projects on this machine. ### Option 2: List Available Projects First If you want to see what projects have logs, ask: ``` "List all projects with Claude Code logs" "Show me which projects I've worked on" "What projects do I have session logs for?" ``` **Claude will:** 1. List all project directories in `~/.claude/projects/` 2. Show the project path for each 3. Display number of sessions and date range 4. Let you pick which one to analyze **Example output:** ``` 📂 Available Projects with Logs: 1. ~/code/youtube/transcript/mcp Sessions: 12 | Date range: Nov 1-9, 2025 | Size: 3.5MB 2. ~/code/my-app Sessions: 45 | Date range: Oct 15-Nov 9, 2025 | Size: 12MB 3. ~/code/experiments Sessions: 8 | Date range: Nov 5-7, 2025 | Size: 1.2MB Which project would you like to analyze? ``` ### Option 3: Analyze a Specific Project If you already know the project path, specify it directly: ``` "Analyze my prompt quality for the project under ~/code/youtube/transcript/mcp" "Analyze my prompt quality for /Users/username/code/my-app and save it as report.md" "Show me token usage for the project in ~/code/experiments" "What tools do I use most in the ~/code/my-app project?" ``` **Key points:** - Use the **full project path** or **relative path with ~** - The path should match your actual project directory - Claude will analyze ONLY the logs for that specific project ### Saving Reports You can request reports to be saved: ``` "Analyze prompt quality for ~/code/my-project and save as docs/analysis.md" "Generate a full report for all projects and save to reports/monthly-review.md" ``` ### Understanding Project Paths **Your logs are organized like this:** ``` ~/.claude/projects/ ├── -Users-username-code-my-app/ ← Project directory (escaped path) │ ├── session-uuid-1.jsonl ← Session log │ ├── session-uuid-2.jsonl │ └── session-uuid-3.jsonl ├── -Users-username-code-experiments/ │ └── session-uuid-4.jsonl ``` **How to reference projects:** - Your actual project: `/Users/username/code/my-app` - Log directory: `~/.claude/projects/-Users-username-code-my-app/` - In your prompt: "Analyze ~/code/my-app" or "/Users/username/code/my-app" Claude will automatically find the corresponding log directory. ### What Gets Analyzed **For each project, Claude analyzes:** - All `.jsonl` session files in that project's log directory - User prompts and Claude's responses - Tool usage patterns - Token consumption - Timestamps and session duration - Files modified **Time ranges:** - By default: Last 30 days of logs - You can specify: "last week", "last 7 days", "this month", etc. - Or provide specific dates: "from Nov 1 to Nov 9" ### Limitations ⚠️ **This skill can ONLY analyze:** - ✅ Logs stored on **THIS machine** in `~/.claude/projects/` - ✅ Projects you've worked on **using Claude Code on this computer** - ✅ Sessions that **still have log files** (not deleted) ❌ **Cannot analyze:** - ❌ Logs from other machines or cloud storage - ❌ Projects you worked on elsewhere - ❌ Deleted or archived session logs - ❌ Sessions from other Claude interfaces (web, mobile) ## Prompt Engineering Best Practices (Claude Official Guidelines) When analyzing prompt quality, reference these official Claude prompt engineering principles: ### The Golden Rule **"Show your prompt to a colleague with minimal context. If they're confused, Claude will likely be too."** Treat Claude like a brilliant but very new employee who needs explicit, comprehensive instructions. ### Hierarchy of Prompt Engineering Techniques (Most to Least Effective) 1. **Be Clear and Direct** ⭐ Most Important - Provide contextual information (purpose, audience, workflow, end goal) - Be specific about expectations - Use numbered or bulleted step-by-step instructions - Specify output format and constraints - Define what successful task completion looks like 2. **Use Examples (Multishot Prompting)** - Demonstrate desired output format - Show variations and edge cases - Provide context for the task - Use high-quality, representative examples 3. **Let Claude Think (Chain of Thought)** - Break complex tasks into step-by-step processes - Allow thinking time/space - Request reasoning before conclusions 4. **Use XML Tags** - Structure prompts with XML for clarity - Separate different types of information - Make parsing and understanding easier 5. **Give Claude a Role (System Prompts)** - Set context with persona/expertise - Define domain knowledge - Establish tone and approach 6. **Prefill Claude's Response** - Guide output format - Set the right starting point 7. **Chain Complex Prompts** - Break large tasks into smaller steps - Use outputs from one prompt as inputs to next ### Common Prompt Problems to Identify **❌ Vague/Unclear:** - "fix the bug" - "make it better" - "update the component" - "write a function" **✅ Clear/Specific:** - "fix the authentication error in src/auth/login.ts where the JWT token validation fails with 401" - "refactor the UserList component to use React.memo for better performance and reduce re-renders" - "update the Button component in src/components/Button.tsx to use the new design system colors from design-tokens.ts" - "write a TypeScript function that validates email addresses using RFC 5322 standard and returns a boolean" ### Key Indicators of Good Prompts 1. **Includes Context:** - File paths when referencing code - Error messages when debugging - Expected behavior or outcome - Constraints or requirements 2. **Specific Instructions:** - Clear, actionable steps - Defined output format - Success criteria 3. **Appropriate Scope:** - Focused on one task - Not too broad or ambiguous - Realistic complexity 4. **Professional Communication:** - Clear language - Organized structure - Complete information ### When Analyzing Prompts, Score Them On: 1. **Clarity** (0-10): How clear and unambiguous is the request? 2. **Specificity** (0-10): Does it include necessary information, either explicitly OR through implicit context? - **Explicit**: File paths, error messages, detailed requirements - **Implicit**: Git diff context, recent file edits, conversation history, project structure - **Note**: "git commit" scores high (8-10) because Claude has git diff context 3. **Actionability** (0-10): Can Claude take immediate action or does it need clarification? 4. **Scope** (0-10): Is the task appropriately sized and focused? **Scoring Guide:** - 8-10: Excellent prompt, minimal clarification needed (includes context-rich brief prompts) - 5-7: Good prompt, minor clarification possible - 3-4: Needs improvement, missing key information - 0-2: Poor prompt, requires significant clarification **Context-Aware Scoring Examples:** - ✅ "git commit" = 9/10 (brief but has full git diff context) - ✅ "run tests" = 8/10 (project structure provides test command context) - ❌ "fix the bug" = 2/10 (brief AND no context - which bug? where?) - ✅ "fix authentication bug in src/auth/login.ts - JWT fails with 401" = 10/10 (explicit details) ## Understanding Context in Prompt Quality **CRITICAL INSIGHT:** Brevity is NOT always a problem. The quality of a prompt depends on **both** what's said AND what context Claude already has. ### The Two Dimensions of Prompt Quality 1. **Explicit Information** - What the user types 2. **Implicit Context** - What Claude can infer from the environment **A great prompt provides enough information for Claude to act, whether explicitly or implicitly.** ### Types of Context Claude Has Access To #### 1. Environmental Context Context Claude can see from the current state of the workspace: **✅ Git Context:** - `git diff` showing what changed - File modifications Claude just made - Previous commits in the session - **Example:** "git commit" → Claude can see all changes, will generate excellent commit message **✅ File Context:** - Files recently read or edited - Files in the current workspace - Code that was just discussed or modified - **Example:** "edit this function" → Claude knows which file and function from previous context **✅ Build/Test Context:** - Project structure (package.json, Cargo.toml, etc.) - Test suites and frameworks in use - Build configurations - **Example:** "run tests" → Claude knows the project's test command #### 2. Conversation Context Context from the ongoing discussion: **✅ Previous Discussion:** - Feature just discussed or designed - Problem being debugged - Implementation approach agreed upon - **Example:** "implement it" → Follows discussion about what to implement **✅ Follow-up Requests:** - Building on previous work - Iterating on a solution - Refining based on feedback - **Example:** "try the other approach" → Refers to alternatives discussed #### 3. Missing Context (RED FLAG) Situations where brevity IS a problem: **❌ No Prior Discussion:** - First message in a session - Switching to a completely new topic - **Example:** "fix the bug" → Which bug? Where? **❌ Ambiguous References:** - Using "it", "this", "that" without clear referent - Multiple possible interpretations - **Example:** "optimize it" → Optimize what? **❌ No Environmental Clues:** - No files in context - No recent changes to reference - No clear scope - **Example:** "update the component" → Which one? ### Recognizing Context-Rich Brief Prompts ✅ **These are EXCELLENT prompts, not problems:** ``` ✅ "git commit" Context: Git diff visible, files changed Why it's good: Claude has everything needed for a great commit message ✅ "git push" Context: Just committed changes Why it's good: Clear action, obvious target ✅ "run tests" Context: Project structure visible Why it's good: Claude knows the test framework and command ✅ "build it" Context: Just finished implementing a feature Why it's good: Build process is obvious from project type ✅ "npm test" Context: Node project, package.json visible Why it's good: Standard command with clear meaning ✅ "yes" / "no" / "1" / "2" Context: Answering Claude's question Why it's good: Direct response to options presented ✅ "continue" Context: Claude paused and asked for confirmation Why it's good: Clear instruction to proceed ✅ "try that" Context: Just discussed an alternative approach Why it's good: Conversation context makes "that" unambiguous ``` ### Recognizing Context-Poor Vague Prompts ❌ **These NEED more information:** ``` ❌ "fix the bug" Context: None - no error shown, no file mentioned Why it's bad: Which bug? Where? What's broken? ✅ Better: "fix the authentication error in src/auth/login.ts where JWT validation fails with 401" ❌ "optimize it" Context: None - no performance issue discussed Why it's bad: Optimize what? For what goal? ✅ Better: "optimize the UserList component to reduce re-renders when parent updates" ❌ "make it better" Context: None - "better" is subjective Why it's bad: Better how? What's the success criteria? ✅ Better: "refactor the function to be more readable by extracting the validation logic" ❌ "update the component" Context: Multiple components exist, none in current scope Why it's bad: Which component? What updates? ✅ Better: "update the Button component in src/components/Button.tsx to use the new color tokens" ``` ### How to Score Context-Rich vs Context-Poor Prompts When analyzing prompts, consider: **High Score (8-10):** Brief + High Context - "git commit" after making changes - "run tests" in a clear project structure - "yes" answering Claude's question - "implement it" after discussing approach **Medium Score (5-7):** Somewhat ambiguous but workable - "fix the error" when error was just shown - "try again" when previous attempt failed - "update it" when only one thing was recently discussed **Low Score (0-4):** Brief + Low Context - "fix the bug" with no prior context - "optimize it" with no performance discussion - "make it better" with no criteria defined - "update the component" with multiple candidates ### Key Takeaway for Analysis **When analyzing logs, celebrate efficient communication:** - ✅ **GOOD:** User says "git commit" → Claude has git diff → Generates excellent message - ❌ **BAD:** User says "fix the bug" → Claude has no error context → Must ask for clarification **The goal is NOT to make every prompt long. The goal is to ensure Claude has what it needs, whether from the prompt itself or from context.** ## Log File Location All Claude Code sessions are logged at: `~/.claude/projects/` **Directory Structure:** - Each project has a directory named with escaped path: `-Users-username-path-to-project/` - Each session is a `.jsonl` file named with a UUID (e.g., `10f49f43-53fd-4910-b308-32ba08f5d754.jsonl`) - Each line in the file is a JSON object representing one event in the conversation ## Log Entry Format ### User Message Entry ```json { "type": "user", "message": { "role": "user", "content": "the user's prompt text" }, "timestamp": "2025-10-25T13:31:07.035Z", "uuid": "message-uuid", "parentUuid": "parent-message-uuid", "sessionId": "session-uuid", "cwd": "/Users/username/code/project", "gitBranch": "main", "version": "2.0.27" } ``` ### Assistant Message Entry ```json { "type": "assistant", "message": { "model": "claude-sonnet-4-5-20250929", "role": "assistant", "content": [ { "type": "text", "text": "The assistant's response text" }, { "type": "tool_use", "id": "tool-uuid", "name": "Read", "input": {"file_path": "/path/to/file"} } ], "usage": { "input_tokens": 1000, "output_tokens": 500, "cache_creation_input_tokens": 2000, "cache_read_input_tokens": 5000 } }, "timestamp": "2025-10-25T13:31:15.369Z", "uuid": "message-uuid", "parentUuid": "parent-message-uuid" } ``` ### File History Snapshot Entry ```json { "type": "file-history-snapshot", "snapshot": { "trackedFileBackups": {}, "timestamp": "2025-10-25T13:31:07.059Z" } } ``` ## Common Tools Used in Logs - `Read` - File reading - `Write` - File writing - `Edit` - File editing - `Bash` - Shell commands - `Grep` - Code search - `Glob` - File pattern matching - `AskUserQuestion` - Asking user for clarification - `TodoWrite` - Managing todo lists - `mcp__*` - Various MCP server tools ## Analysis Tasks ### 0. General Analysis Mode (COMPREHENSIVE REPORT) **When to trigger:** - User asks for "general analysis", "overall analysis", "comprehensive report", "complete overview" - User asks "how am I doing with Claude Code?" or "analyze my Claude Code usage" - User requests "all metrics", "everything", "full report" - When the user first activates this skill and you want to offer value **IMPORTANT:** This is the **premier feature** of Prompt Coach. When triggered, you will: 1. Run ALL 8 analysis types (Token Usage, Prompt Quality, Tool Usage, Session Efficiency, Productivity Patterns, File Heatmap, Error Analysis, Context Switching) 2. Generate ONE comprehensive report combining all insights 3. Use a subagent via Task tool to handle the complexity **How to execute:** ``` Use the Task tool with general-purpose agent: - description: "Generate comprehensive Claude Code analysis report" - subagent_type: "general-purpose" - prompt: "Analyze all Claude Code session logs in ~/.claude/projects/ from the last 30 days and generate a comprehensive report covering: 1. Token Usage & Cost Analysis (with deduplication) 2. Prompt Quality Analysis (context-aware scoring) 3. Tool Usage Patterns (built-in + MCP tools) 4. Session Efficiency Analysis 5. Productivity Time Patterns 6. File Modification Heatmap 7. Error & Recovery Analysis 8. Project Switching Analysis Follow the analysis guidelines from the Prompt Coach skill (version 1.10.0). Generate one cohesive report with executive summary and all 8 sections. Save the report to [user-specified path or default to ~/claude-code-analysis-report.md]" ``` **Report Structure:** ```markdown # Claude Code Usage Analysis Report Generated: [Date] Analysis Period: Last 30 days ## 📊 Executive Summary [High-level overview with key metrics:] - Total cost: $X.XX - Sessions analyzed: X - Average prompt quality: X.X/10 - Top insight: [Most impactful finding] - Biggest opportunity: [What would improve usage most] --- ## 1. 💰 Token Usage & Cost Analysis [Follow guidelines from "1. Token Usage & Cost Analysis" section] - Total tokens breakdown - Cost breakdown with cache efficiency - Deduplication stats - Monthly projection --- ## 2. ✍️ Prompt Quality Analysis [Follow guidelines from "2. Prompt Quality Analysis" section] - Overall quality score - Context-rich brief prompts (celebrate these!) - Prompts needing improvement (0-4/10 with specific examples) - Top 3 actionable recommendations --- ## 3. 🛠️ Tool Usage Patterns [Follow guidelines from "3. Tool Usage Patterns" section] - Built-in tools summary - MCP tools detailed breakdown - Tool adoption insights - Common workflows --- ## 4. ⚡ Session Efficiency Analysis [Follow guidelines from "4. Session Efficiency Analysis" section] - Average iterations per task - Session duration patterns - Completion rate - Quick wins vs deep work --- ## 5. 🕐 Productivity Time Patterns [Follow guidelines from "5. Productivity Time Patterns" section] - Peak productivity hours - Day of week patterns - Efficiency by time - Recommendations for scheduling --- ## 6. 🔥 File Modification Heatmap [Follow guidelines from "6. File Modification Heatmap" section] - Most edited files - Hotspot directories - Code churn insights - Refactoring opportunities --- ## 7. 🐛 Error & Recovery Analysis [Follow guidelines from "7. Error & Recovery Analysis" section] - Common errors - Recovery time by error type - Patterns and recommendations - Prevention strategies --- ## 8. 🔄 Project Switching Analysis [Follow guidelines from "8. Project Switching Analysis" section] - Number of active projects - Time distribution - Context switching cost - Focus optimization tips --- ## 🎯 Top 5 Recommendations [Synthesize the most impactful recommendations across all 8 analyses] 1. **[Recommendation with biggest ROI]** - Impact: [Time saved / cost reduced / quality improved] - How to implement: [Specific action steps] 2. **[Second most impactful]** ... [Continue for top 5] --- ## 💡 Next Steps [3-5 concrete action items the user should take this week] 1. [ ] [Specific, measurable action] 2. [ ] [Specific, measurable action] 3. [ ] [Specific, measurable action] --- *Report generated by Prompt Coach v1.10.0* *Analysis based on session logs from ~/.claude/projects/* ``` ### 1. Token Usage & Cost Analysis **When asked about tokens, costs, or spending:** **Steps:** 1. Use Bash to list recent .jsonl files and get file sizes: ```bash find ~/.claude/projects -name "*.jsonl" -type f -mtime -30 -exec ls -lh {} \; ``` 2. Read a representative sample of files (5-10 recent ones) 3. **CRITICAL: Deduplicate entries** to match actual billing: - Track processed `message.id + requestId` combinations in a Set - Skip duplicate entries (Claude Code logs streaming responses multiple times) - Only count each unique API call once **Deduplication logic:** ``` For each line in JSONL: - Extract message.id and requestId - Create hash: `${message.id}:${requestId}` - If hash already processed: SKIP this entry - Otherwise: mark hash as processed and count tokens ``` 4. Parse each **unique** entry and extract `usage` data: - `input_tokens` - `output_tokens` - `cache_creation_input_tokens` - `cache_read_input_tokens` 5. **CRITICAL: Use model-specific pricing** - Extract model from `message.model` field: **Claude API Pricing (Current as of Nov 2025):** | Model | Input | Output | Cache Writes | Cache Reads | |-------|-------|--------|--------------|-------------| | **Opus 4.1** (`claude-opus-4-1-*`) | $15/1M | $75/1M | $18.75/1M | $1.50/1M | | **Sonnet 4.5** (`claude-sonnet-4-5-*`) ≤200K | $3/1M | $15/1M | $3.75/1M | $0.30/1M | | **Sonnet 4.5** (`claude-sonnet-4-5-*`) >200K | $6/1M | $22.50/1M | $7.50/1M | $0.60/1M | | **Haiku 4.5** (`claude-haiku-4-5-*`) | $1/1M | $5/1M | $1.25/1M | $0.10/1M | | **Haiku 3.5** (`claude-haiku-3-5-*`) | $0.80/1M | $4/1M | $1/1M | $0.08/1M | | **Opus 3** (`claude-3-opus-*`) | $15/1M | $75/1M | $18.75/1M | $1.50/1M | **NOTE:** Opus is 5x more expensive than Sonnet! **Model Detection:** ``` For each unique entry: - Extract model from message.model field - Match model name to pricing table - Group tokens by model - Calculate cost per model using correct rates ``` 6. **Understand your pricing model** and tailor recommendations: 📊 **For Pay-Per-Use Users (API billing):** - Cost optimization IS directly relevant - Switching to Haiku for simple tasks saves money - Model selection has immediate cost impact - Cache optimization reduces billable tokens 📊 **For Subscription Users (Claude Pro, Team, Enterprise):** - Cost optimization recommendations are LESS relevant - **BUT cache optimization is STILL valuable** because: - ⚡ **Faster responses** - Anthropic caches your context server-side for ~5 minutes - ⚡ **Better UX** - Less waiting for context to process - ⚡ **Improved efficiency** - Claude can respond faster with cached context - ⚡ **Rate limit benefits** - Better cache usage may help with rate limits - Focus on **session efficiency** and **prompt quality** instead of model costs 💡 **How to tell which pricing model you're on:** - If these costs matter to your budget → You're pay-per-use - If you pay a fixed monthly fee → You're on subscription - When in doubt, ask the user! 7. Present breakdown: - Total tokens by type (deduplicated) - Cost breakdown (matches actual billing) - Cache efficiency (savings from cache reads) - Breakdown by model if multiple models used - Monthly projection if analyzing less than a month - **Deduplication stats**: Show how many duplicates were skipped **Example Output:** ``` 📊 Token Usage Analysis (Last 30 Days) 💰 **Total Cost: $288.13** (matches actual Anthropic billing) ## By Model: **Sonnet 4.5** (3,662 calls, 81.2%) - Input: 191,659 ($0.58) - Output: 135,505 ($2.03) - Cache writes: 20,010,946 ($75.04) - Cache reads: 240,989,306 ($72.30) - **Subtotal: $149.95** **Opus 4.1** (769 calls, 17.1%) - Input: 3,176 ($0.05) - Output: 30,440 ($2.28) - Cache writes: 2,595,837 ($48.67) - Cache reads: 57,156,831 ($85.74) - **Subtotal: $136.74** ⚠️ 5x more expensive than Sonnet! **Haiku 4.5** (77 calls, 1.7%) - Input: 54,265 ($0.05) - Output: 19,854 ($0.10) - Cache writes: 93,590 ($0.12) - Cache reads: 666,241 ($0.07) - **Subtotal: $0.34** 📋 Deduplication Summary: - Total entries found: 44,036 - Duplicate entries: 6,444 (14.6%) - Unique API calls: 4,508 - Duplication factor: 9.77x ⚡ Cache Efficiency: 99.9% hit rate 💰 Cache savings: $806.79 --- ## 💡 Recommendations **📌 For Pay-Per-Use Users:** Your Opus usage (17.1%) costs $136.74 - that's 91% of your total spend! - Consider using Sonnet for complex tasks instead (5x cheaper) - Reserve Opus for truly difficult problems only - **Potential savings:** ~$80-100/month by shifting Opus → Sonnet **📌 For Subscription Users:** Cache optimization is still valuable for speed: - Keep sessions focused on single tasks (maintains cache) - Avoid context switching (breaks cache, slows responses) - Your 99.9% cache hit rate is excellent - keep it up! **📌 For Everyone:** Haiku is underutilized (1.7% of calls): - Perfect for: file reads, basic edits, simple commands - Consider using Haiku for 20-30% of tasks - Much faster responses for simple operations ``` ### 2. Prompt Quality Analysis **When asked about prompt quality or clarity:** **🤖 Recommended Approach: Use a Subagent** For prompt quality analysis, **use the Task tool with general-purpose agent** to handle the complexity of context-aware analysis: ``` Use Task tool with: - subagent_type: "general-purpose" - Provide the project path or "analyze all projects" - Include instructions to apply v1.5.0 context-aware analysis from this skill ``` **Why use a subagent:** - Reading multiple .jsonl session files (could be 10-100+ sessions with hundreds of prompts) - Context-aware analysis is nuanced (checking if prompts respond to Claude's questions) - Detecting context-rich brief prompts (git commands, follow-ups, valid responses) - Requires judgment for scoring (0-10) considering explicit + implicit context - Generating comprehensive reports with real examples and insights - LLM agent is much better than bash/grep scripts for subjective pattern recognition **The agent should:** 1. Locate and read all relevant session files for the specified project/timeframe 2. Apply the context-aware analysis logic defined below 3. Generate a comprehensive report following the example output format 4. Return the complete analysis for saving or presentation **Steps (for the subagent to follow):** 1. Read recent session files (last 7-14 days) 2. For each session, identify user prompts (type: "user") 3. Check if the following assistant message contains: - **AskUserQuestion tool usage** - Signal that prompt needed clarification (but ignore if user explicitly requested options/choices) - **Clarifying questions in text** - Look for patterns like: - "Could you clarify" - "Which file" - "What do you mean" - "Can you specify" - "I need more information" - "Please provide" - "Would you like me to" - "Should I" - "Do you want" 4. **Detect Vague Prompt Patterns** - Look for these red flags in user prompts that trigger clarifications: **⚠️ CRITICAL: Context-Aware Analysis** Before flagging ANY prompt as vague, **check the conversation context**: 1. **Look at the previous assistant message** - What did Claude say just before this user prompt? 2. **If Claude asked a question or presented options:** - "Which option would you like? 1, 2, or 3?" - "Should I proceed? (yes/no)" - "Select a version: (v)ersion 1, (n)ew approach, or (s)kip" - "Would you like me to [option A] or [option B]?" 3. **Then single-word responses are PERFECT, not vague:** - "1", "2", "3" → Answering Claude's option question ✅ - "yes", "no" → Answering Claude's yes/no question ✅ - "v", "n", "s" → Answering Claude's selection question ✅ - "continue" → Responding to Claude's confirmation request ✅ **ONLY flag as vague if:** - It's a standalone prompt (not answering Claude's question) - It doesn't clearly answer what Claude asked - It's the user initiating a new request without context --- **✅ Context-Rich Brief Prompts (DO NOT FLAG as vague)** Before flagging a brief standalone prompt as vague, check if it has **implicit context** from the environment: **Git Commands** (Claude has git diff context): - "git commit", "git push", "git add", "git commit and push" - "commit", "push" - **Why not vague:** Claude can see git diff and will generate excellent commit messages - **Score these:** 8-10 (Excellent - Claude has full context from git status/diff) **Build/Test Commands** (Claude has project structure context): - "run tests", "build", "npm test", "npm run build", "cargo build", "make" - "test it", "build it" - **Why not vague:** Project files show test framework and build configuration - **Score these:** 8-10 (Excellent - Claude knows the project structure) **Standard Development Commands** (clear from context): - "install dependencies", "npm install", "yarn install" - "lint", "format", "check types" - **Why not vague:** Package managers and tools are evident from project files - **Score these:** 7-9 (Good - standard commands with clear meaning) **Follow-up Prompts** (Claude just did work): - "try again", "revert it", "undo that" - "edit this function", "update that", "fix this" - **Why not vague:** Recent file reads/edits provide context for "it", "this", "that" - **Score these:** 7-9 (Good - conversation context makes references clear) - **Check:** Look at previous assistant messages - did Claude just read/edit files? **Continuation Prompts** (building on previous work): - "continue", "keep going", "finish it" - "do the same for [similar item]" - **Why not vague:** Refers to work Claude was already doing - **Score these:** 7-9 (Good - continuation of established task) **IMPORTANT:** Only recognize these patterns as context-rich if: 1. The prompt matches common git/build/test patterns 2. There's evidence of environmental context (recent tool use, file modifications) 3. It's a follow-up to previous work Claude did in the session If a brief prompt does NOT match these patterns and has no environmental/conversation context, then apply the vague prompt flags below. --- **🚩 Missing File Context** (standalone prompts only): - "fix the bug" (no file mentioned, initiating request) - "update the component" (which one? initiating request) - "change the function" (where? initiating request) - "add error handling" (to which file/function? initiating request) **🚩 Vague Action Words** (standalone prompts only): - "improve", "optimize", "make better", "enhance", "clean up" - These need specific success criteria (faster by how much? reduce what?) - NOT vague if answering "What would you like me to do?" **🚩 Missing Error Details** (standalone prompts): - "fix the error" (what error? where?) - "it's not working" (what's the expected vs actual behavior?) - "debug this" (what's the symptom?) **🚩 Ambiguous Scope** (standalone prompts): - "refactor the code" (which code? to what pattern?) - "add tests" (for what? unit/integration/e2e?) - "update the docs" (which docs? with what info?) **🚩 Missing Approach/Method** (standalone prompts): - "add authentication" (OAuth? JWT? Sessions?) - "implement caching" (Redis? Memory? File-based?) - "add logging" (to console? file? service?) 5. **Extract Real Examples** - Pull actual vague prompts from logs and show what Claude asked for clarification: - User's original prompt - What Claude had to ask - What the improved prompt should have been 6. Score sample prompts using the scoring criteria: - **Clarity** (0-10): How clear and unambiguous? - **Specificity** (0-10): Includes file paths, error messages, context? - **Actionability** (0-10): Can Claude act immediately? - **Scope** (0-10): Appropriately sized and focused? 7. Calculate: - Total user prompts - Prompts needing clarification - Clarification rate (% of prompts that triggered AskUserQuestion or clarifying questions) - Average prompt quality score - **Most common missing elements** (file paths, error messages, success criteria, etc.) 8. Categorize issues using official prompt engineering problems: - **Missing context** (no file paths, no error messages) - % of clarifications - **Too vague/broad** (no specific expectations) - % of clarifications - **Missing success criteria** (no definition of "done") - % of clarifications - **Ambiguous requests** (multiple valid interpretations) - % of clarifications - **Missing approach** (multiple implementation methods possible) - % of clarifications 9. **CRITICAL: Generate "Areas for Improvement" Section** - For prompts scoring 0-4/10: - List EVERY prompt that scored 3-4/10 or lower - For EACH low-scoring prompt, provide: - The exact prompt text from logs - Score (e.g., 3/10) - Problem explanation (what's missing or unclear) - Context available at that moment - What likely happened (Claude's clarification) - Better version of the same prompt with specifics - Why the better version works - Time saved estimate - Calculate total impact of these improvements - Identify common patterns across these low-scoring prompts **This section is MANDATORY if ANY prompts score 0-4/10** 10. Provide specific recommendations based on **Prompt Engineering Best Practices** above, with focus on: - Most impactful improvements (what would reduce clarifications most) - Specific templates/patterns for common tasks - Real examples from their logs showing before/after **Example Output:** ``` 📝 Prompt Quality Analysis (Last 14 Days) Total prompts: 145 Context-aware analysis: 145 prompts categorized Average prompt score: 6.8/10 (Very Good!) ✅ Context-Rich Brief Prompts Identified: 23 (16%) Examples: "git commit", "run tests", "build", "npm install" These score 8-10/10 - excellent use of environmental context! 📊 Prompt Category Breakdown: - Excellent (8-10): 45 prompts (31%) - Context-rich OR detailed - Good (5-7): 71 prompts (49%) - Adequate information - Needs Work (0-4): 29 prompts (20%) - Brief AND low context Clarifications needed: 29 (20%) - Down from typical 35%! 🚩 Most Common Issues (context-poor prompts only): 1. Missing file context: 18 prompts (when no files in scope) 2. Missing error details: 14 prompts (when debugging without error shown) 3. Missing success criteria: 16 prompts (vague goals like "optimize") 4. Missing approach: 12 prompts (when multiple methods possible) 🔴 Real Examples from Your Logs (context-poor prompts): **Example 1: Missing File Context** ❌ Your prompt: "fix the bug" 🤔 Claude asked: "Which file has the bug? What's the error message or symptom?" ✅ Better prompt: "fix the authentication bug in src/auth/login.ts where JWT validation fails with 401 error" 📉 Cost: +2 minutes, +1 iteration **Example 2: Vague Action Words** ❌ Your prompt: "optimize the component" 🤔 Claude asked: "Which component? What performance issue? What's the target?" ✅ Better prompt: "optimize UserList component in src/components/UserList.tsx by adding React.memo to reduce unnecessary re-renders when parent updates" 📉 Cost: +3 minutes, +1 iteration **Example 3: Missing Approach** ❌ Your prompt: "add caching" 🤔 Claude asked: "Where should caching be added? What caching strategy? (Redis, memory, file-based?)" ✅ Better prompt: "add Redis caching to the API responses in src/api/client.ts with 5-minute TTL, similar to how we cache user data" 📉 Cost: +4 minutes, +2 iterations **Example 4: Missing Error Details** ❌ Your prompt: "it's not working" 🤔 Claude asked: "What's not working? What's the expected behavior vs what's happening?" ✅ Better prompt: "the login form isn't submitting - clicking the submit button does nothing, no network requests in console, expected to see POST to /api/auth/login" 📉 Cost: +2 minutes, +1 iteration --- ## ⚠️ Areas for Improvement (Prompts Scoring 0-4/10) **CRITICAL: If there are prompts scoring 0-4/10, list EVERY SINGLE ONE with specific examples:** While most of your prompts are good, here are the **X specific prompts that scored 3-4/10** and need improvement: ### Prompts That Need Work **Example 1: Too Brief Without Context** (Score: 3/10) ❌ **Your prompt:** "test" - **Problem:** No context about what to test, which tests to run, or which file - **Context available:** None - standalone request - **What happened:** Claude likely had to ask: "Which tests? Unit tests? Integration tests? For which component?" ✅ **Better prompt:** "run the unit tests for the YouTube transcript fetcher in src/index.test.ts" - **Why better:** Specifies test type, component, and file path - **Time saved:** ~2 minutes **Example 2: Vague Action Without Specifics** (Score: 4/10) ❌ **Your prompt:** "update the docs" - **Problem:** Doesn't specify which documentation or what updates to make - **Context available:** Multiple doc files exist - **What happened:** Claude needed clarification on which docs and what information to add ✅ **Better prompt:** "update README.md to include installation instructions and usage examples for the get-transcript tool" - **Why better:** Specific file, specific sections, clear requirements - **Time saved:** ~3 minutes [Continue for ALL prompts scoring 0-4/10...] ### Impact of These Improvements **Current state:** - X prompts needed significant clarification - Average Y minutes lost per unclear prompt - **Total time lost: ~Z minutes** **If improved:** - Direct answers without clarification - **Potential time savings: ~Z minutes** in this project alone - **Annualized savings:** ~N hours/year on similar projects ### Common Patterns to Avoid Based on these X examples, watch out for: 1. **🚩 Standalone brief prompts without context** - "test", "fix", "update" → Need specifics 2. **🚩 Vague action verbs without details** - "improve", "optimize", "make it work" → Need measurable outcomes 3. **🚩 Missing file paths** - "update the docs", "add validation" → Include file names 4. **🚩 Ambiguous pronouns** - "it", "this", "that" without clear referent → Name the specific component 5. **🚩 No error context** - "fix the error" → Include error message and location 6. **🚩 No success criteria** - "improve performance" → Define baseline and target --- 📊 Prompt Quality Score Breakdown: - Excellent (8-10): 23 prompts (16%) - Clear, specific, actionable - Good (5-7): 71 prompts (49%) - Minor improvements possible - Needs Work (3-4): 38 prompts (26%) - Missing key information - Poor (0-2): 13 prompts (9%) - Requires significant clarification 📉 Impact Analysis: - 29 prompts needed clarification (down from typical 35%!) - Average time lost per clarification: 2.8 minutes - Total time lost to context-poor prompts: ~1.4 hours - **Potential time savings: ~45 minutes by improving remaining context-poor prompts** 🌟 What You're Doing Right (Keep It Up!): ✅ **Context-Rich Brief Prompts: 23 prompts (16%)** Examples from your logs: - "git commit" → Claude used git diff to create perfect commit message - "run tests" → Claude knew your test framework from package.json - "build" → Clear action with obvious build process - "npm install" → Standard command, no ambiguity 💰 Time saved: ~1.5 hours by NOT over-explaining when context is clear! ✅ **Valid Responses: 6 prompts** - Answered Claude's questions concisely ("yes", "1", "2") - Perfect communication efficiency ✅ **Detailed Prompts: 42 prompts (29%)** - Clear file paths, error messages, and success criteria - These work great even without environmental context **Keep using this efficient approach!** You're already saving time by trusting Claude to use available context. 🎯 Your Top 3 Improvements (Maximum Impact): 💡 Note: You're already using context well with git commands and build tools! **1. Include File Paths When No Files in Scope (18 clarifications)** When to add file paths: When you're not already working with the file When NOT needed: After reading/editing a file, or when only one file is relevant Template: "[action] in [file path] [details]" Examples: - ❌ "fix the bug" (no file in context) - ✅ "fix the validation error in src/utils/validator.ts where email regex fails" - ✅ "update the Button component in src/components/Button.tsx to match design system" 💰 Impact: Would eliminate ~18 clarifications (~50 min saved) **2. Provide Error Details When Debugging (23% of clarifications)** Template: "fix [error message] in [file] - expected [X], getting [Y]" Examples: - "fix 'Cannot read property of undefined' error in src/hooks/useAuth.ts line 42 - expected user object, getting undefined" - "fix TypeScript error TS2322 in src/types/User.ts - type mismatch on email field" 💰 Impact: Would eliminate ~12 clarifications (~25 min saved) **3. Define Success Criteria for Vague Actions (30% of clarifications)** Instead of: "optimize", "improve", "make better", "clean up" Use: "[action] to achieve [specific measurable outcome]" Examples: - "optimize database queries in src/db/users.ts to reduce response time from 800ms to <200ms" - "refactor UserList component to use virtual scrolling and handle 10,000+ items smoothly" 💰 Impact: Would eliminate ~15 clarifications (~40 min saved) 💡 Quick Win: Apply these templates to your next 10 prompts and watch your clarification rate drop! 💪 You're doing well! Your prompts are 65% effective. Focus on these 3 improvements and you'll hit 85%+ effectiveness, saving ~1-2 hours per week. ``` ### 3. Tool Usage Patterns **When asked about tools, workflows, or how they code:** **Steps:** 1. Read recent session files 2. Extract all tool_use blocks from assistant messages 3. Count usage by tool name 4. **Group tools into categories:** - **Built-in Claude Code tools**: Read, Write, Edit, Bash, Grep, Glob, Task, TodoWrite, WebFetch, WebSearch, NotebookEdit, SlashCommand - **MCP/3rd party tools**: Any tool starting with `mcp__` or custom tools - Parse MCP tool names to extract server name (e.g., `mcp__playwright__navigate` → playwright server) 5. Identify patterns: - Total built-in tool usage (one summary line) - Individual MCP tool usage (detailed breakdown) - MCP server adoption (which servers are being used) - Common workflows with MCP tools - Tool success/failure rates 6. Provide recommendations focused on MCP tool adoption and usage **Example Output:** ``` 🛠️ Tool Usage Patterns (Last 30 Days) Built-in Claude Code Tools: └─ Total: 955 uses (Read: 450, Edit: 220, Bash: 150, Write: 89, Grep: 34, Glob: 12) 🌟 MCP & 3rd Party Tools: 1. playwright (server) ████████████████████ 287 uses ├─ navigate 98 uses ├─ screenshot 76 uses ├─ click 54 uses ├─ fill 32 uses └─ evaluate 27 uses 2. browserbase (server) ████████████ 156 uses ├─ stagehand_navigate 45 uses ├─ stagehand_act 52 uses ├─ stagehand_extract 39 uses └─ screenshot 20 uses 3. youtube-transcript (server) ████ 34 uses └─ get-transcript 34 uses 4. pdf-reader (server) ██ 18 uses ├─ read-pdf 12 uses └─ search-pdf 6 uses 💡 Insights: 🌟 Great MCP adoption! You're using 4 different MCP servers → 495 MCP tool calls vs 955 built-in tools → MCP tools account for 34% of your tool usage ✅ Playwright is your most-used MCP server → Heavily used for browser automation → Good mix of navigation, interaction, and screenshots 🚀 Browserbase + Stagehand pattern detected → You're leveraging AI-powered browser control → 156 uses show strong automation workflow 💡 Opportunity: Consider these MCP servers you haven't tried: → @modelcontextprotocol/server-filesystem for advanced file ops → @modelcontextprotocol/server-sqlite for database work → @modelcontextprotocol/server-github for PR/issue management 📊 Common MCP workflows: 1. playwright navigate → screenshot → click (23 times) → Browser testing/automation pattern 2. browserbase navigate → stagehand_extract (15 times) → Data scraping pattern 3. youtube-transcript get-transcript → Edit (12 times) → Video content analysis workflow ``` ### 4. Session Efficiency Analysis **When asked about productivity, efficiency, or iterations:** **Steps:** 1. Read recent session files 2. For each session (group by sessionId): - Count total messages - Count user messages (iterations) - Measure duration (first to last timestamp) - Check for "completion signals": - Bash commands with `git commit` - Successful builds (`npm run build`, `cargo build`) - Test runs (`npm test`, `pytest`) 3. Calculate metrics: - Average iterations per session - Average session duration - Task completion rate - Time to first action (user prompt → first tool use) **Example Output:** ``` ⚡ Session Efficiency Analysis Sessions analyzed: 45 Average iterations per task: 3.5 Median iterations: 2 Session duration (avg): 18 minutes Completion patterns: - Quick wins (<5 min): 23 sessions (51%) - Standard tasks (5-30 min): 15 sessions (33%) - Deep work (>30 min): 7 sessions (16%) 💡 Insights: ✅ You're efficient! 51% of tasks complete in <5 minutes 📊 Iteration breakdown: - 1 iteration: 12 sessions - Clear requirements - 2-3 iterations: 20 sessions - Normal back-and-forth - 4+ iterations: 13 sessions - Unclear requirements or complex tasks 🎯 Tip: Sessions with 4+ iterations often started with vague prompts. Being more specific upfront could save ~8 min/task. ``` ### 5. Productivity Time Patterns **When asked about productive hours, when they work best:** **Steps:** 1. Read session files from last 30 days 2. Extract all timestamps and parse them 3. Group sessions by: - Hour of day (0-23) - Day of week (Mon-Sun) - Weekend vs weekday 4. For each time bucket, calculate: - Number of sessions - Average iterations - Average session duration - Efficiency score (tasks completed / iterations) **Example Output:** ``` 🕐 Productivity Time Patterns (Last 30 Days) Peak productivity hours: 1. 14:00-17:00 ████████████ (32 sessions, 2.1 avg iterations) 2. 09:00-12:00 ████████ (24 sessions, 2.8 avg iterations) 3. 20:00-23:00 ████ (15 sessions, 4.2 avg iterations) Most efficient: 14:00-17:00 (afternoon) - 40% fewer iterations than average - 25% faster completion time - Higher task completion rate Least efficient: 20:00-23:00 (evening) - 50% more iterations needed - More clarification requests - More Bash command failures Day of week patterns: Tuesday: ████████ Most productive Wednesday: ███████ Thursday: ██████ Monday: ████ Slower start Friday: ███ Winding down 💡 Recommendation: Schedule complex tasks between 2-5pm on Tue-Thu ``` ### 6. File Modification Heatmap **When asked about what files they work on, code hotspots:** **Steps:** 1. Read recent session files 2. Extract all tool_use blocks with names: Edit, Write 3. Parse the file_path from each tool's input 4. Count modifications per file 5. Group by directory to find hotspots **Example Output:** ``` 🔥 File Modification Heatmap (Last 30 Days) Most edited files: 1. src/components/Button.tsx ████████████ 47 edits 2. src/utils/api.ts ████████ 32 edits 3. src/hooks/useAuth.ts ██████ 23 edits 4. tests/components/Button.test.tsx █████ 19 edits 5. src/types/index.ts ████ 16 edits Hotspot directories: 1. src/components/ ██████████████████ 89 edits 2. src/utils/ ████████ 45 edits 3. tests/ ██████ 34 edits 💡 Insights: 🔥 Button.tsx is your hottest file (47 edits) → Consider if this component needs refactoring → High edit frequency can indicate code smell ✅ Good test coverage signal: → 19 edits to Button.test.tsx → You're maintaining tests alongside code 📊 Component-heavy development: → 62% of edits in src/components/ → UI-focused work this month ``` ### 7. Error & Recovery Analysis **When asked about errors, problems, or troubleshooting:** **Steps:** 1. Read recent session files 2. Look for error indicators in Bash tool results: - Non-zero exit codes - Common error patterns (npm ERR!, error:, failed, etc.) 3. Measure recovery patterns: - Time between error and fix - Number of attempts - Common error types **Example Output:** ``` 🐛 Error & Recovery Analysis Errors encountered: 23 Common errors: 1. npm install failures ████████ 8 occurrences → Avg recovery time: 4.5 min → Common cause: Node version mismatch 2. TypeScript compile errors ██████ 6 occurrences → Avg recovery time: 8 min → Common cause: Type mismatches 3. Test failures ████ 4 occurrences → Avg recovery time: 12 min 💡 Recommendations: 1. npm install issues: → Add .nvmrc file to project → Use `nvm use` before installing → Saves ~4 min per occurrence 2. TypeScript errors: → Run `tsc --watch` during development → Catch errors before committing ``` ### 8. Project Switching Analysis **When asked about context switching, focus time:** **Steps:** 1. Read session files from multiple project directories 2. Track when `cwd` (current working directory) changes between sessions 3. Calculate: - Number of project switches per day - Time spent per project - Overhead of switching (idle time between projects) **Example Output:** ``` 🔄 Project Switching Analysis (Last 7 Days) Active projects: 5 Total switches: 23 Avg switches per day: 3.3 Time distribution: 1. ~/code/main-app ████████████ 12 hours (55%) 2. ~/code/side-project ████ 4 hours (18%) 3. ~/code/dotfiles ███ 3 hours (14%) 4. ~/code/experiments ██ 2 hours (9%) 5. ~/code/scripts █ 1 hour (4%) Context switching cost: - Avg overhead per switch: 12 minutes - Total overhead this week: 4.6 hours - Estimated productivity loss: 20% 💡 Recommendation: You switched projects 23 times in 7 days. Consider: - Time-blocking: Dedicate specific days to specific projects - Batch similar tasks: Do all dotfile updates in one session - Your focus time is best on main-app (fewer interruptions) ``` ## General Guidelines ### When Analyzing Logs: 1. **Sample Intelligently** - For recent data: Read last 5-10 .jsonl files - For historical: Use Bash to find files by date, sample evenly - Very large files (>10MB): Read first/last N lines 2. **Parse JSON Carefully** - Each line is separate JSON - Handle malformed lines gracefully - Watch for truncated last lines 3. **Respect Privacy** - These are personal coding sessions - Don't repeat user's code or prompts verbatim unless illustrative - Focus on patterns, not specifics 4. **Provide Actionable Insights** - Always include "💡 Tips" or "Recommendations" - Compare to benchmarks when possible - Suggest specific improvements 5. **Use Visualizations** - ASCII charts for distributions - Emoji indicators for priority/severity - Tables for comparisons ### Finding Specific Information: **To find all sessions from a specific project:** ```bash ls -la ~/.claude/projects/-Users-username-code-projectname/ ``` **To find sessions from a date range:** ```bash find ~/.claude/projects -name "*.jsonl" -newermt "2025-01-01" -ls ``` **To quickly check total log size:** ```bash du -sh ~/.claude/projects ``` **To count total sessions:** ```bash find ~/.claude/projects -name "*.jsonl" | wc -l ``` ## Example Queries You Can Answer ### 🌟 General Analysis (Comprehensive Report - NEW!) - **"Give me a general analysis of my Claude Code usage"** ← Recommended! - **"Analyze my overall Claude Code usage"** ← Recommended! - "Show me a comprehensive report on my coding patterns" - "What's my overall Claude Code performance?" - "How am I doing with Claude Code?" - "Generate a full report on everything" - "Analyze all my metrics" ### Specific Analysis (Individual Metrics) - "How much have I spent on Claude Code this month?" - "Am I writing good prompts?" - "What tools do I use most?" - "When am I most productive?" - "Which files do I edit most often?" - "How efficient are my sessions?" - "Show me my coding patterns" - "What did I work on last week?" - "How much time do I spend context switching?" - "What errors do I encounter most?" ### Project Discovery - "List all projects with Claude Code logs" - "Show me which projects I've worked on" - "What projects do I have session logs for?" - "Which project have I spent the most time on this week?" ### Project-Specific Analysis - "Analyze my prompt quality for the project under ~/code/youtube/transcript/mcp" - "Show me token usage for the project in ~/code/my-app" - "What tools do I use most in the ~/code/experiments project?" - "How efficient are my sessions for /Users/username/code/my-project?" - "Which files do I edit most in the ~/code/dotfiles project?" - "Analyze my prompt quality for ~/code/my-app and save it as reports/prompt-analysis.md" ## Important Notes - Always use existing tools (Read, Bash, Grep) - you have file access - Parse JSON yourself - you can do this natively - Show specific examples from actual logs when helpful - Give actionable, personalized recommendations - Be encouraging but honest about areas for improvement - Calculate costs accurately with current pricing - **CRITICAL (v1.8.0+):** Always deduplicate token usage entries using `message.id + requestId` hash to match actual billing. Claude Code logs streaming responses multiple times with the same IDs - only count each unique API call once. - **CRITICAL (v1.10.0+):** Always use model-specific pricing. Extract model from `message.model` field and apply correct rates. Opus is 5x more expensive than Sonnet! - **NEW (v1.10.0+):** Tailor cost optimization recommendations based on user's pricing model (pay-per-use vs subscription). Cache optimization is valuable for BOTH but for different reasons. - **NEW (v1.9.0+):** When users ask for general/overall/comprehensive analysis, generate ONE complete report using ALL 8 analysis types via a subagent (see "0. General Analysis Mode" section)