/clarify

name: clarify
description: "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."
argument-hint: "[target]"
user-invocable: false

Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.

MANDATORY PREPARATION

Invoke /frontend-design — 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 /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context.

---

Assess Current Copy

Identify what makes the text unclear or ineffective:

1. **Find clarity problems**:

• **Jargon**: Technical terms users won't understand
• **Ambiguity**: Multiple interpretations possible
• **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
• **Length**: Too wordy or too terse
• **Assumptions**: Assuming user knowledge they don't have
• **Missing context**: Users don't know what to do or why
• **Tone mismatch**: Too formal, too casual, or inappropriate for situation

2. **Understand the context**:

• Who's the audience? (Technical? General? First-time users?)
• What's the user's mental state? (Stressed during error? Confident during success?)
• What's the action? (What do we want users to do?)
• What's the constraint? (Character limits? Space limitations?)

**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.

Plan Copy Improvements

Create a strategy for clearer communication:

• **Primary message**: What's the ONE thing users need to know?
• **Action needed**: What should users do next (if anything)?
• **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
• **Constraints**: Length limits, brand voice, localization considerations

**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.

Improve Copy Systematically

Refine text across these common areas:

Error Messages

**Bad**: "Error 403: Forbidden" **Good**: "You don't have permission to view this page. Contact your admin for access."

**Bad**: "Invalid input" **Good**: "Email addresses need an @ symbol. Try: name@example.com"

**Principles**:

• Explain what went wrong in plain language
• Suggest how to fix it
• Don't blame the user
• Include examples when helpful
• Link to help/support if applicable

Form Labels & Instructions

**Bad**: "DOB (MM/DD/YYYY)" **Good**: "Date of birth" (with placeholder showing format)

**Bad**: "Enter value here" **Good**: "Your email address" or "Company name"

**Principles**:

• Use clear, specific labels (not generic placeholders)
• Show format expectations with examples
• Explain why you're asking (when not obvious)
• Put instructions before the field, not after
• Keep required field indicators clear

Button & CTA Text

**Bad**: "Click here" | "Submit" | "OK" **Good**: "Create account" | "Save changes" | "Got it, thanks"

**Principles**:

• Describe the action specifically
• Use active voice (verb + noun)
• Match user's mental model
• Be specific ("Save" is better than "OK")

Help Text & Tooltips

**Bad**: "This is the username field" **Good**: "Choose a username. You can change this later in Settings."

**Principles**:

• Add value (don't just repeat the label)
• Answer the implicit question ("What is this?" or "Why do you need this?")
• Keep it brief but complete
• Link to detailed docs if needed

Empty States

**Bad**: "No items" **Good**: "No projects yet. Create your first project to get started."

**Principles**:

• Explain why it's empty (if not obvious)
• Show next action clearly
• Make it welcoming, not dead-end

Success Messages

**Bad**: "Success" **Good**: "Settings saved! Your changes will take effect immediately."

**Principles**:

• Confirm what happened
• Explain what happens next (if relevant)
• Be brief but complete
• Match the user's emotional moment (celebrate big wins)

Loading States

**Bad**: "Loading..." (for 30+ seconds) **Good**: "Analyzing your data... this usually takes 30-60 seconds"

**Principles**:

• Set expectations (how long?)
• Explain what's happening (when it's not obvious)
• Show progress when possible
• Offer escape hatch if appropriate ("Cancel")

Confirmation Dialogs

**Bad**: "Are you sure?" **Good**: "Delete 'Project Alpha'? This can't be undone."

**Principles**:

• State the specific action
• Explain consequences (especially for destructive actions)
• Use clear button labels ("Delete project" not "Yes")
• Don't overuse confirmations (only for risky actions)

Navigation & Wayfinding

**Bad**: Generic labels like "Items" | "Things" | "Stuff" **Good**: Specific labels like "Your projects" | "Team members" | "Settings"

**Principles**:

• Be specific and descriptive
• Use language users understand (not internal jargon)
• Make hierarchy clear
• Consider information scent (breadcrumbs, current location)

Apply Clarity Principles

Every piece of copy should follow these rules:

1. **Be specific**: "Enter email" not "Enter value" 2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity) 3. **Be active**: "Save changes" not "Changes will be saved" 4. **Be human**: "Oops, something went wrong" not "System error encountered" 5. **Be helpful**: Tell users what to do, not just what happened 6. **Be consistent**: Use same terms throughout (don't vary for variety)

**NEVER**:

• Use jargon without explanation
• Blame users ("You made an error" → "This field is required")
• Be vague ("Something went wrong" without explanation)
• Use passive voice unnecessarily
• Write overly long explanations (be concise)
• Use humor for errors (be empathetic