clarify

# Clarify Handle user confusion by verifying intent, explaining actual behavior, and determining if there's a real issue. **Primary goal**: Clarify and explain, not fix. Most confusion stems from misunderstanding or forgetting, not from bugs. ## Activation Triggers - "confused", "I'm confused", "this is confusing" - "I don't understand", "doesn't make sense", "makes no sense" - "wait, shouldn't it...", "but I thought..." - "why is this happening", "why does this..." - "I expected X but got Y" - "this is wrong", "something's off" - frustration signals, contradictory statements - questions that reveal misconceptions about system behavior ## Important Context Users often: - **Work on multiple projects in parallel** and may confuse behaviors between them - **Forget how things were implemented** especially after time away - **Have outdated mental models** based on old versions or different projects - **Mix up similar concepts** from different codebases or frameworks But also: - **Users are experienced developers** - their instincts are often correct - **Real bugs exist** - about half of confusion cases point to actual issues - **User expectations are reasonable** - if something feels wrong, investigate thoroughly **Do not assume either way.** Investigate before concluding. Both outcomes are equally valid: - User misremembered/mixed things up -> clarify with evidence - System has a genuine issue -> proceed to plan mode for fix ## Workflow ### Phase 1: Identify the Confusion 1. **Extract the core question** - What specifically is the user asking about? 2. **Identify the expectation** - What did the user expect to happen? 3. **Identify the reality** - What is actually happening? 4. **Locate the gap** - Where is the misalignment? 5. **Consider context mixing** - Could user be thinking of a different project/feature? Categories of confusion: - **Memory gap** - user forgot how it works, needs a reminder - **Project mixing** - user confused this with another project they're working on - **Outdated mental model** - user's understanding is based on old behavior - **Architectural** - misunderstanding system design, component relationships, data flow - **Behavioral** - expecting different runtime behavior than what occurs - **Configuration** - settings not producing expected results - **Documentation** - docs don't match implementation or are unclear - **Conceptual** - misunderstanding underlying concepts or patterns - **Implementation** - code doesn't work as assumed ### Phase 2: Investigate Before explaining, gather evidence: 1. **Read relevant code** - Understand actual implementation 2. **Check configuration** - Verify settings and their effects 3. **Review documentation** - See what's documented vs actual behavior 4. **Trace the flow** - Follow execution path if behavioral confusion Do not guess or assume. Investigate the actual system state. ### Phase 3: Explain (Gently) Structure the explanation with patience and care: 1. **Acknowledge the confusion** - Validate that it's understandable, confusion is normal 2. **State the expectation** - "You expected X to do Y" 3. **State the reality** - "Actually, X does Z because..." 4. **Explain why** - Provide the reasoning/design decision behind the behavior 5. **Show evidence** - Point to specific code, config, or docs Tone guidelines: - Be gentle, not condescending - user may have simply forgotten - Avoid "you're wrong" framing - use "here's how it actually works" - If user mixed up projects, clarify without judgment - Remind that it's easy to forget details when working on multiple things Keep explanations: - Concrete, not abstract - Backed by evidence from the codebase - Focused on the specific case, not general theory ### Phase 4: Assess **Start with the most common cases first:** **A) Memory gap - user simply forgot** - User implemented this but forgot how it works - System is working exactly as designed - Resolution: gentle reminder with code references **B) Project mixing - wrong mental context** - User is thinking of a different project or codebase - This project works differently than user's current mental model - Resolution: clarify which project this is and how it differs **C) Outdated understanding** - System changed since user last worked on it - Or user's mental model never matched reality - Resolution: explain current behavior with evidence **D) Documentation issue** - System works correctly but docs are misleading/missing - Resolution: suggest updating docs, may use EnterPlanMode **E) Configuration issue** - System can do what user expects but isn't configured for it - Resolution: suggest configuration changes **F) Real issue - design or implementation problem** - User's expectation is reasonable AND system genuinely doesn't meet it - This indicates a bug, design flaw, or missing feature - Resolution: **MUST proceed to Phase 5** ### Phase 5: Plan the Fix (for real issues) If Phase 4 identified a real issue (category F): #### Step 1: Summarize and Assess Scope Explain to user what fixing this involves: **Scope categories:** - **Trivial** - Simple fix, single file, no side effects - **Localized** - Few files, contained to one component - **Moderate** - Multiple components affected, requires testing - **Significant** - Cross-cutting concern, affects multiple subsystems - **Architectural** - Fundamental design change, may require rethinking approach Be explicit: "This is a [scope] change because [reason]." User must understand the magnitude before deciding to proceed. #### Step 2: Present Options (if multiple approaches exist) When there are multiple valid solutions, use **AskUserQuestion** tool to present choices: - List 2-4 options with clear trade-off descriptions - Put recommended option first with "(Recommended)" suffix - Include "Do nothing" as an option when relevant: - Issue is cosmetic or low-impact - Workaround exists - Fix is risky relative to benefit - Issue is edge case that rarely occurs - Let user choose the approach #### Step 3: Proceed to Plan Mode After user confirms or selects an approach: 1. **Use EnterPlanMode** - Create implementation plan for the chosen approach 2. Plan should reflect the scope assessment from Step 1 **CRITICAL**: Do not attempt to fix issues without planning. Always use EnterPlanMode for: - Bug fixes - Design changes - Missing features - Documentation updates that require code understanding ## Response Format ``` ## Understanding Your Confusion **What you expected**: [user's expectation] **What actually happens**: [actual behavior] ## Why This Happens [Explanation with evidence - code references, config, docs] ## Assessment [One of: Not an issue / Documentation issue / Real issue / Configuration issue] [If real issue]: This is a real issue that should be addressed. I recommend switching to plan mode to design a proper fix. Should I enter plan mode to plan the solution? ``` ## Guidelines **Mindset:** - Users are experienced developers - trust their instincts - About half of confusion cases are real issues, half are misunderstandings - Users work on many projects - confusion between them is normal - Memory is fallible - be patient when reminding how things work **Approach:** - Never dismiss confusion as "user error" - investigate first - Never assume something is broken without evidence either - Always back explanations with evidence from the actual codebase - If unsure, ask clarifying questions before investigating - Keep the tone helpful, not condescending - If the confusion reveals a real problem, treat it as valuable feedback - Don't over-explain - focus on the specific confusion, not general tutorials **Fixing:** - **Investigate first, then determine outcome** - If it's a misunderstanding -> explain clearly with evidence - If it's a real issue -> proceed to plan mode for fix - **Use EnterPlanMode when investigation confirms a genuine bug/flaw**