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