1---
  2name: clarify
  3description: "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing."
  4argument-hint: "[target]"
  5user-invocable: true
  6---
  7
  8Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
  9
 10## MANDATORY PREPARATION
 11
 12Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: audience technical level and users' mental state in context.
 13
 14---
 15
 16## Assess Current Copy
 17
 18Identify what makes the text unclear or ineffective:
 19
 201. **Find clarity problems**:
 21   - **Jargon**: Technical terms users won't understand
 22   - **Ambiguity**: Multiple interpretations possible
 23   - **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
 24   - **Length**: Too wordy or too terse
 25   - **Assumptions**: Assuming user knowledge they don't have
 26   - **Missing context**: Users don't know what to do or why
 27   - **Tone mismatch**: Too formal, too casual, or inappropriate for situation
 28
 292. **Understand the context**:
 30   - Who's the audience? (Technical? General? First-time users?)
 31   - What's the user's mental state? (Stressed during error? Confident during success?)
 32   - What's the action? (What do we want users to do?)
 33   - What's the constraint? (Character limits? Space limitations?)
 34
 35**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
 36
 37## Plan Copy Improvements
 38
 39Create a strategy for clearer communication:
 40
 41- **Primary message**: What's the ONE thing users need to know?
 42- **Action needed**: What should users do next (if anything)?
 43- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
 44- **Constraints**: Length limits, brand voice, localization considerations
 45
 46**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
 47
 48## Improve Copy Systematically
 49
 50Refine text across these common areas:
 51
 52### Error Messages
 53**Bad**: "Error 403: Forbidden"
 54**Good**: "You don't have permission to view this page. Contact your admin for access."
 55
 56**Bad**: "Invalid input"
 57**Good**: "Email addresses need an @ symbol. Try: name@example.com"
 58
 59**Principles**:
 60- Explain what went wrong in plain language
 61- Suggest how to fix it
 62- Don't blame the user
 63- Include examples when helpful
 64- Link to help/support if applicable
 65
 66### Form Labels & Instructions
 67**Bad**: "DOB (MM/DD/YYYY)"
 68**Good**: "Date of birth" (with placeholder showing format)
 69
 70**Bad**: "Enter value here"
 71**Good**: "Your email address" or "Company name"
 72
 73**Principles**:
 74- Use clear, specific labels (not generic placeholders)
 75- Show format expectations with examples
 76- Explain why you're asking (when not obvious)
 77- Put instructions before the field, not after
 78- Keep required field indicators clear
 79
 80### Button & CTA Text
 81**Bad**: "Click here" | "Submit" | "OK"
 82**Good**: "Create account" | "Save changes" | "Got it, thanks"
 83
 84**Principles**:
 85- Describe the action specifically
 86- Use active voice (verb + noun)
 87- Match user's mental model
 88- Be specific ("Save" is better than "OK")
 89
 90### Help Text & Tooltips
 91**Bad**: "This is the username field"
 92**Good**: "Choose a username. You can change this later in Settings."
 93
 94**Principles**:
 95- Add value (don't just repeat the label)
 96- Answer the implicit question ("What is this?" or "Why do you need this?")
 97- Keep it brief but complete
 98- Link to detailed docs if needed
 99
100### Empty States
101**Bad**: "No items"
102**Good**: "No projects yet. Create your first project to get started."
103
104**Principles**:
105- Explain why it's empty (if not obvious)
106- Show next action clearly
107- Make it welcoming, not dead-end
108
109### Success Messages
110**Bad**: "Success"
111**Good**: "Settings saved! Your changes will take effect immediately."
112
113**Principles**:
114- Confirm what happened
115- Explain what happens next (if relevant)
116- Be brief but complete
117- Match the user's emotional moment (celebrate big wins)
118
119### Loading States
120**Bad**: "Loading..." (for 30+ seconds)
121**Good**: "Analyzing your data... this usually takes 30-60 seconds"
122
123**Principles**:
124- Set expectations (how long?)
125- Explain what's happening (when it's not obvious)
126- Show progress when possible
127- Offer escape hatch if appropriate ("Cancel")
128
129### Confirmation Dialogs
130**Bad**: "Are you sure?"
131**Good**: "Delete 'Project Alpha'? This can't be undone."
132
133**Principles**:
134- State the specific action
135- Explain consequences (especially for destructive actions)
136- Use clear button labels ("Delete project" not "Yes")
137- Don't overuse confirmations (only for risky actions)
138
139### Navigation & Wayfinding
140**Bad**: Generic labels like "Items" | "Things" | "Stuff"
141**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
142
143**Principles**:
144- Be specific and descriptive
145- Use language users understand (not internal jargon)
146- Make hierarchy clear
147- Consider information scent (breadcrumbs, current location)
148
149## Apply Clarity Principles
150
151Every piece of copy should follow these rules:
152
1531. **Be specific**: "Enter email" not "Enter value"
1542. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
1553. **Be active**: "Save changes" not "Changes will be saved"
1564. **Be human**: "Oops, something went wrong" not "System error encountered"
1575. **Be helpful**: Tell users what to do, not just what happened
1586. **Be consistent**: Use same terms throughout (don't vary for variety)
159
160**NEVER**:
161- Use jargon without explanation
162- Blame users ("You made an error" → "This field is required")
163- Be vague ("Something went wrong" without explanation)
164- Use passive voice unnecessarily
165- Write overly long explanations (be concise)
166- Use humor for errors (be empathetic instead)
167- Assume technical knowledge
168- Vary terminology (pick one term and stick with it)
169- Repeat information (headers restating intros, redundant explanations)
170- Use placeholders as the only labels (they disappear when users type)
171
172## Verify Improvements
173
174Test that copy improvements work:
175
176- **Comprehension**: Can users understand without context?
177- **Actionability**: Do users know what to do next?
178- **Brevity**: Is it as short as possible while remaining clear?
179- **Consistency**: Does it match terminology elsewhere?
180- **Tone**: Is it appropriate for the situation?
181
182Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
183