clarify

What this skill does

# 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**