ryanthedev Skill: clarify
Understand what the user needs before committing to design work.
LLMs default to assuming rather than asking — models overwhelmingly proceed without asking even when information is missing. This skill serves as the design workflow's clarifier: it classifies what's unclear about a design request and generates targeted questions to resolve it before any visual or structural work begins.
adaptive-questioning.md at ${CLAUDE_SKILL_DIR}/references/adaptive-questioning.md is a shared reference: the plan pipeline's clarify gates also link to it (design lifecycle checkpoints use it for mode-switching).
Your output is a conversation: clarifying questions, differential examples, restatements. Think out loud WITH the user — collaborative exploration, not interrogation.
Classifying What's Unclear
Not all gaps are the same. Classifying the type determines what kind of question to ask.
Fault Types
Intention faults — The real design goal isn't recoverable from the request.
- Vague objectives: "Make it look better" / "make it more modern" / "make it pop" (better how? for whom? in what direction?)
- Indirect intent: "Can you check if this color works?" (often means "please fix the color system")
- Contextual irrelevance: user introduces an unrelated visual concern mid-design
Premise faults — An assumption in the request is wrong or unresolvable.
- Missing brand context: "Match our brand" with no DESIGN.md, style guide, or reference supplied
- False artifact state: "Update the existing tokens" when no DESIGN.md exists in the project
- Capability mismatch: asking for a visual output the current context can't supply (e.g., "export as Figma" when only HTML is possible)
Parameter faults — Required design details are missing or conflicting.
- Missing register: "Design a landing page" (brand or product register? marketing or SaaS tool?)
- Missing audience/device: "Make it responsive" (primary breakpoints? phone-first or desktop-first?)
- Missing mood/personality: "Clean and professional" (minimal and cold? warm and approachable? editorial and bold?)
- Contradictions: "Keep it simple but show everything"
Expression faults — The language prevents unique design interpretation.
- Lexical ambiguity: "Clean up the UI" (reduce density? simplify color? tighten spacing? all of the above?)
- Scope ambiguity: "Make it more accessible" (WCAG AA contrast only? motion sensitivity? keyboard navigation? all three?)
- Referential ambiguity: "Update that component" (which one? in which context?)
Ambiguity Direction
Once you've identified a gap, classify which direction it pulls — this shapes your question:
| Direction | Signal | Clarification Action |
|---|---|---|
| Semantic | Design term has multiple valid meanings | Disambiguate: "do you mean X or Y?" |
| Too broad | Clear intent but scope spans multiple pillars | Specify: "which concern matters most right now?" |
| Too narrow | Request is oddly specific for the likely design goal | Generalize: "what's the broader outcome you're after?" |
For Design Tasks Specifically
Three concrete ways a design request becomes ambiguous:
- Missing goal: the why is absent — only the what is stated ("add a hero section" with no brief on purpose or audience)
- Missing premises: design constraints are unstated (brand colors, target device, tone, accessibility tier)
- Ambiguous terminology: vague design words used where precise ones are needed ("modern" vs "minimal + editorial", "professional" vs "product-register restrained")
Inconsistencies between design requirements are easy to miss. Explicitly check whether parts of the request conflict (e.g., "bold and vibrant" + "calm and trustworthy" pull in opposite directions).
Generating Questions
Think in Hypotheses
Don't start with "what should I ask?" Start with "what are the plausible design directions?" Then find the question whose answer eliminates the most of them.
- Generate 2–4 competing design interpretations of the request
- Identify what distinguishes them — the axis of disagreement
- Ask about that axis
Example:
- Request: "Redesign the dashboard"
- Interpretation A: Reduce visual noise — strip cards, tighten spacing, neutral palette
- Interpretation B: Establish brand identity — introduce accent, typeface, personality
- Interpretation C: Improve usability — rethink hierarchy, surface key actions, reduce cognitive load
- Axis: is this a visual/brand problem, a clarity/usability problem, or a density problem?
- Question: "What's the main complaint about the current dashboard — it doesn't feel like the brand, it's hard to read, or it's overwhelming?"
One question targeting the axis of disagreement beats three questions about visual details.
Select for Information Gain
Among possible questions, ask the one that maximally reduces uncertainty across your interpretations. If question A would split your hypotheses 50/50 and question B would split them 90/10, ask A — it's more informative regardless of the answer.
Target convergence in 3–5 rounds. Beyond that, returns diminish sharply.
Concrete Over Abstract
When possible, show the user what different interpretations produce rather than asking abstract questions:
- Weak: "What kind of visual tone are you after?"
- Strong: "If you mean editorial — high contrast, tight spacing, expressive type — the palette leans into dark neutrals. If you mean approachable — rounded forms, warm color, open spacing — it goes the other way. Which direction feels closer?"
Show differential design directions. Let the user pick based on observable descriptions, not abstract labels.
Five Clarification Strategies
Match your approach to the fault type:
| Strategy | When | Example |
|---|---|---|
| Ask for parameter | Specific design detail is missing | "What's the primary device — phone or desktop?" |
| Disambiguate | Multiple valid design directions exist | "By 'modern,' do you mean minimal/flat or bold/expressive?" |
| Propose alternatives | Brand constraints make the request impossible as stated | "No DESIGN.md found. We can establish a design DNA first, or proceed in wireframe mode and layer tokens later." |
| Confirm risk | High-stakes design decision that's hard to undo | "Locking DESIGN.md commits the token system. Proceed, or adjust the palette first?" |
| Report blocker | A design prerequisite is genuinely absent | "No brand reference supplied. The core design mode establishes a design DNA — should we run that first?" |
Question Quality
Attributes
Every question should pass these checks:
| Attribute | Test |
|---|---|
| Focused | Addresses ONE gap — no compound questions |
| Answerable | User can answer from what they already know |
| Discriminative | The answer meaningfully narrows design directions |
| Non-leading | Doesn't presuppose the answer |
| Task-relevant | Directly advances the design work at hand |
| Constructive | Builds toward a confirmed brief, not just gathering data |
Effort Awareness
Estimate the effort each question requires from the user:
| Effort | Example | Policy |
|---|---|---|
| Low | "Phone-first or desktop-first?" | Ask freely — user already knows |
| Medium | "What's the emotional register — brand or product?" | Ask only if it materially changes the direction |
| High | "What does your current design system's token naming look like?" | Don't ask — investigate DESIGN.md / codebase yourself |
The principle: ask about intent, goals, and brand context (the user's knowledge). Figure out technical and structural details yourself.
Managing the Conversation
Track Intent State
Maintain two mental sets as the conversation progresses:
- Confirmed (+): design directions, constraints, and goals the user has validated
- Ruled out (−): directions the user has rejected or that contradict confirmed information
Score remaining design directions by alignment with confirmed items and conflict with ruled-out items. This naturally narrows the space with each turn.
Decouple the Decisions
Three separate questions, in order:
- Should I clarify? — Is there meaningful ambiguity that would change the design direction?
- What type of clarification? — Which fault type and strategy apply?
- How do I phrase it? — What specific question, with what framing?
Don't collapse these. Deciding to clarify and blurting out the first question that comes to mind skips the targeting step.
Short-Circuit Rules
- If the brief is clear and you have no competing design directions, proceed directly.
- When asking and not-asking would produce equally good design outcomes, don't ask. Favor action on ties.
- If the user signals "just do it" or "whatever works," switch to confirmatory mode rather than going silent — state your design assumptions so the user can object. See adaptive-questioning.md for mode-switching protocol and the genuine-low-stakes exception.
Anti-Patterns
Last reviewed: 2026-07
| Pattern | Problem | Instead |
|---|---|---|
| Proceeding without checking | Default execution bias — wrong design direction is expensive | Run detection as a separate pass first |
| Asking about implementation details | "Which CSS framework?" is not a design question | Figure it out; ask about brand/audience/goal |
| Rapid-fire question lists | Feels like an intake form, not a collaboration | 1–3 questions max per turn |
| Asking what you could read from DESIGN.md | Wastes their time | Read DESIGN.md first, ask about what it doesn't cover |
| Over-asking on clear briefs | Delays work, erodes trust | If the brief is clear, proceed |
| Abstract questions | Hard for users to reason about visual direction | Show differential design directions |
| Leading questions | Biases response, masks intent | Open-ended, or balanced options |
| One round and done | Complex design briefs need iteration | Continue until directions converge |
| Asking when outcomes are equivalent | Unnecessary friction | Favor direct action on ties |
Non-Duplication Note
This skill handles design brief ambiguity — the gaps that prevent knowing what design to make. It does NOT replace the core design-for-ai skill's intent detection (which mode to run: design, surface, fonts, color, audit, enhance, polish). If the user's request is design-mode-clear but the design brief itself is underspecified, invoke clarify. If the request is mode-unclear, the core skill routes it.
Chain
| After | Next |
|---|---|
| Ambiguity resolved, brief confirmed | Return to calling command with goal/audience/brand/constraints/register |
| New ambiguity surfaces during design work | Re-enter clarify loop |