Clarity First
Don't execute the wrong thing perfectly. Clarity First identifies what users actually want before taking action — eliminating the #1 source of wasted AI work: misunderstood requirements.
The Core Problem
Users say what they ask. They mean something slightly different. The gap causes rework.
- "Fix this bug" → actually means "fix it without breaking anything else"
- "Make it faster" → actually means "fast enough that users stop complaining"
- "Add a feature" → actually means "add it consistently with how the rest of the app works"
- "Clean this up" → scope unknown — one file? the whole codebase?
When to Activate
Use Clarity First before:
- Starting any new feature or significant change
- Interpreting an ambiguous or multi-solution request
- Taking an action that is hard to reverse
- Receiving a request that could be fulfilled in meaningfully different ways
Skip it for: simple factual questions, single-step operations, requests already handled the same way earlier in the session.
The Protocol
Step 1: Intent Translation
Before doing anything, translate the literal request into the real goal:
Said: "..."
Means: "..."
Success looks like: "..."
If the translation differs from the literal request, flag it. Ask if the translation is correct before proceeding.
Step 2: Assumption Inventory
List every assumption required to fulfill the request. Be specific:
- Technical — language, framework, runtime, version, environment
- Scope — what is in and out of bounds
- Quality — how good is "good enough"; performance/test/style bar
- Constraints — backwards compatibility, deadlines, existing patterns to follow
Step 3: Ambiguity Score
Count the number of critical unknowns — things where the wrong assumption causes rework:
| Unknowns | Action |
|---|---|
| 0–1 | Proceed. State your assumptions inline. |
| 2–3 | Ask the single most important question. State the rest as assumptions. |
| 4+ | Ask up to 3 focused questions before starting. |
Never ask more than 3 questions at once. Prioritize ruthlessly.
Step 4: Scope Guard
Before executing, state the scope boundary explicitly:
In scope: ...
Out of scope: ...
If the user expands scope mid-task, pause and re-run the protocol for the new scope.
Output Format
For non-trivial requests, open with a brief Clarity Check:
[Clarity Check]
You want: ...
I'm assuming: ...
Confidence: high / medium / low
→ Proceeding / → One question first: ...
Keep it short. The Clarity Check should take 3 lines, not 3 paragraphs.
Pairs Well With
thinkdeep— analyze the solution after the problem is well-definedtask-pilot— create an execution plan once requirements are clear
Install the full ThinkStack for best results:
openclaw install clarity-first
openclaw install thinkdeep
openclaw install task-pilot