Clarify - one reading of the ask before any design
A design built on a guessed requirement is rebuilt when the guess is found out, usually after the
build. Clarifying is cheap at the start and expensive at every step after it. Gate on AMBIGUITY, not
on size or domain count: a one-file change with two readings is clarified, a large crisp one is not.
The measurements behind these rules live in references/evidence.md - an audit appendix, not a run-time load.
When to use
- Fires before designing, planning or dispatching work on a feature, change or greenfield ask that can be read more than one way: an unclear scope, user, success criterion or constraint, 'make it better', 'add support for X', a vague bug report, or a brief a seat returned as NEEDS_CONTEXT.
- The requirements check that settles, through AskUserQuestion, which reading the user means before any design.
- Not for how to build it: an implementation choice (library, structure, naming, placement) is decided, stated inline and recorded in the plan, which is the plan-writing habit's job.
The loop
List the readings. Read the ask for what changes, for whom, what must keep working and what
must go away. Each place where two defensible answers lead to different designs is a reading.
An ask that cites a source row - a spec table row, an audit finding, a card - is read against
the row whole: hold the user's words against EVERY clause of it (the defect it describes and the
fix it names), and a clause the words leave uncovered is a second reading - asked, or under AUTO
recorded as a ## Decisions line naming the dropped half - an uncovered clause otherwise goes
unbuilt and ships.
One reading left: record the ask verbatim as the requirement and go on to the design - nothing
to ask.
Ask one question at a time. Through AskUserQuestion: the question names the fork and why it
matters, 2-3 concrete options, the recommended one marked, free text left open (plain-text
options where the tool is absent). One question per turn - a batch of five gets one answered.
<the fork, one line> - <why the two readings build different things>. Which do you mean?
- '<the likelier reading> (Recommended)' - <what the design then builds>
- '<the other reading>' - <what the design then builds>
Until one reading is left. Each answer can open or close other readings - re-read the ask with
it before the next question.
Record the answers verbatim. They are the requirement the design builds on: the plan's
Asked: line, or the requirements_source a dispatched designer receives. A paraphrase loses
exactly the detail that was asked about.
What is never asked
The implementation - library, structure, naming, pattern, placement. Those are the design's calls,
made with a precedent and recorded in the plan's ## Decisions ledger, never bounced to the user.
Who asks
Only the main session can talk to the user. A dispatched seat handed an ambiguous brief returns
NEEDS_CONTEXT with the readings it found instead of guessing, and the session that dispatched it
runs this loop before it dispatches again.
1---2name: habits-clarify3description: "Use before designing a change that can be read more than one way - 'make it better', 'add support for X'. Not for build choices, which a plan records."4metadata:5 source: https://skillmd.com/skills/envoydev/habits-clarify6---78# Clarify - one reading of the ask before any design910A design built on a guessed requirement is rebuilt when the guess is found out, usually after the11build. Clarifying is cheap at the start and expensive at every step after it. Gate on AMBIGUITY, not12on size or domain count: a one-file change with two readings is clarified, a large crisp one is not.1314The measurements behind these rules live in `references/evidence.md` - an audit appendix, not a run-time load.1516## When to use1718- Fires before designing, planning or dispatching work on a feature, change or greenfield ask that can be read more than one way: an unclear scope, user, success criterion or constraint, 'make it better', 'add support for X', a vague bug report, or a brief a seat returned as NEEDS_CONTEXT.19- The requirements check that settles, through AskUserQuestion, which reading the user means before any design.20- Not for how to build it: an implementation choice (library, structure, naming, placement) is decided, stated inline and recorded in the plan, which is the plan-writing habit's job.2122## The loop23241. **List the readings.** Read the ask for what changes, for whom, what must keep working and what25 must go away. Each place where two defensible answers lead to different designs is a reading.26 An ask that cites a source row - a spec table row, an audit finding, a card - is read against27 the row whole: hold the user's words against EVERY clause of it (the defect it describes and the28 fix it names), and a clause the words leave uncovered is a second reading - asked, or under AUTO29 recorded as a `## Decisions` line naming the dropped half - an uncovered clause otherwise goes30 unbuilt and ships.31 One reading left: record the ask verbatim as the requirement and go on to the design - nothing32 to ask.332. **Ask one question at a time.** Through AskUserQuestion: the question names the fork and why it34 matters, 2-3 concrete options, the recommended one marked, free text left open (plain-text35 options where the tool is absent). One question per turn - a batch of five gets one answered.3637 ```ask38 <the fork, one line> - <why the two readings build different things>. Which do you mean?39 - '<the likelier reading> (Recommended)' - <what the design then builds>40 - '<the other reading>' - <what the design then builds>41 ```423. **Until one reading is left.** Each answer can open or close other readings - re-read the ask with43 it before the next question.444. **Record the answers verbatim.** They are the requirement the design builds on: the plan's45 `Asked:` line, or the `requirements_source` a dispatched designer receives. A paraphrase loses46 exactly the detail that was asked about.4748## What is never asked4950The implementation - library, structure, naming, pattern, placement. Those are the design's calls,51made with a precedent and recorded in the plan's `## Decisions` ledger, never bounced to the user.5253## Who asks5455Only the main session can talk to the user. A dispatched seat handed an ambiguous brief returns56NEEDS_CONTEXT with the readings it found instead of guessing, and the session that dispatched it57runs this loop before it dispatches again.