clarify · diff
git:20260826.809b028 to git:20260907.daa0780
64 added, 49 removed. Audit A to A.
---
name: clarify
- description: Clarification protocol — grill an ambiguous request into a Requirements Ledger before any delegation. The chair MUST load this whenever a request arrives carrying ambiguity that would change the work; Rule 0.5 in the core profile only summarizes it.
+ description: Clarification protocol — grill a request into a Requirements Ledger before any delegation, all questions at the START. The chair MUST load this when a job arrives that will be delegated; Rule 0.5 in the core profile only summarizes it.
---
# Clarify Before You Delegate
A worker cannot ask the user anything. Every ambiguity you carry into
a spawn prompt becomes a guess the worker commits to code, and you pay
- for it twice — once building the wrong thing, once rebuilding it. The
- cheapest question is the one asked before the first spawn.
+ for it twice — once building the wrong thing, once rebuilding it.
+ Every question is asked at the START of the job; none in the middle.
- Chair only. A subagent that hits an ambiguity does NOT run this skill:
- it reports the ambiguity to the chair with SendMessage and waits.
+ Chair only. A subagent that hits an ambiguity reports it to the chair
+ with SendMessage and waits.
## The gate
Nothing is delegated, planned, or edited until every ambiguity that
- would change the work is either resolved by an answer or written down
- as an explicit assumption the user can veto. `## Clarified` in the
- ledger is the record, and the spawn guard denies without it.
+ would change the work is resolved by the USER'S ANSWER — never by an
+ assumption. `## Clarified` in the ledger is the record, and the spawn
+ guard denies without it.
- ## Scan — seven axes
+ ## Read first, then ask
+ Never ask what the repo answers: open the files the request touches
+ before the first question. Code shows what IS, never what they WANT —
+ reading feeds the questions, it answers none of them.
+
+ ## Scan — seven axes, at EVERY size
+
Each axis that is unresolved AND would change the work is a question:
1. **Scope edge** — what is deliberately OUT? The unnamed neighbour is
where scope creep lives.
2. **Acceptance** — how is "done" observed? Name the test, the
command, the screen.
3. **Constraints** — backward compatibility, dependencies, budget,
what must not move.
- 4. **Ownership of choices** — which decisions are the user's taste and
- which are yours? Guessing on taste is expensive.
+ 4. **Ownership of choices** — whose taste is each decision? Guessing
+ on taste is expensive.
5. **Priority conflict** — when speed, correctness, and token cost
disagree, which wins here?
6. **Contact with what exists** — which current file, pattern, or
- contract does this touch? Read first; never ask what the repo
- answers.
+ contract does this touch? Read first.
7. **Failure behaviour** — what happens on error, and what does
rollback look like?
## Filter — ask only what changes the work
Before asking: *would a different answer produce different code?* If
- no, do not ask — write the assumption and move on. This filter is what
- makes an uncapped question loop safe. Never ask what you can read; a
- question the repo already answers spends the user's attention on your
- laziness.
+ no, it goes unasked and unwritten. This filter is what makes an
+ uncapped question loop safe.
- ## One question per message
+ ## Always asked — where the work lands
- One question. Wait. The answer re-shapes the map — it closes some
- axes, opens others, and the next question is DERIVED from it, not read
- off a pre-written list. Batching guesses the order and kills the
- derivation.
+ One question is exempt from the filter and asked at EVERY size: does
+ this land on the branch checked out now, or a new one? You cannot
+ infer it — the branch you happen to be on is where the user was
+ working, not a decision about this task.
- No cap. Stop when the scan turns up nothing that would change the
- work, never at a number.
+ ## Ask in rounds, at the start
- Form:
+ Front-load. Put every currently open question into as FEW messages as
+ possible: `AskUserQuestion` carries up to four, `multiSelect` covers
+ scope choices. Answers re-shape the map — they close some axes and
+ open others — so the next round is DERIVED from them, and the loop
+ runs again. No cap on rounds.
- - Choices are nameable (2-4 options) → `AskUserQuestion`, options
- concrete, your recommendation first and marked.
- - Genuinely open → one plain-prose sentence.
+ Stop condition, literal: no `?` is left unanswered under `## Clarified`
+ AND you could write the spec for a worker who cannot ask you anything
+ without guessing at any part of it. "The scan turned up nothing" is
+ what a clean request and a lazy look produce alike, so it is no test.
- State your reading when the answer depends on it: "I read this as X,
- which means Y — right?" is a faster question than "what do you mean?"
+ Each question: one plain sentence, plus one line saying what changes
+ depending on the answer. Nameable choices (2-4) → concrete options,
+ your recommendation first and marked, with its reason. Genuinely
+ open → your reading and its reason: "I would go with X because Y —
+ right?" A recommendation is a PROPOSAL, never a recorded answer:
+ `## Clarified` holds what the USER picked.
## Record, then delegate
Write `## Clarified` at the TOP of ./.workflow/LEDGER*.md, above the
numbered items:
```markdown
## Clarified
- - Q1: <question> -> <answer>
- - Q2: <question> -> <answer>
- - Assumption: <unasked but load-bearing> — say so if wrong
+ - Q1: <question>? -> <the user's answer>
+ - Q2: <question>? -> <the user's answer>
+ - Branch: <where the work lands>
```
- Then the `- [ ] N.` items, each traceable to an answer or an
- assumption. Then spawn. Worker specs cite items, the items carry the
- answers, and no worker has to guess. Answers that arrive mid-task are
- appended, never merged away — a second `## Clarified` block lower in
- the file counts.
+ Then the `- [ ] N.` items, each traceable to an answer. Worker specs
+ cite items, the items carry the answers, and no worker has to guess.
+ A later round is appended as a second `## Clarified` block; the hook
+ reads the union.
- Write answers as **plain bullets**. A numbered checkbox (`- [ ] 1.`)
- is a ledger item, so it closes the section instead of filling it, and
- a `## Clarified` inside a fenced code block is an example, not a
- record.
+ The hook denies the spawn on any bullet with a `?` and no `->`/`→`
+ answer, on an `Assumption:`/`Varsayım:` bullet, on a section with no
+ `Q -> A` line, and on a missing `Branch:`/`Dal:` line. Answers are
+ **plain bullets**: ANY checkbox line reads as a ledger item and ends
+ the section; a `## Clarified` inside a fenced code block is an
+ example, not a record; a divider or a comment is not an answer.
- A genuinely unambiguous request still gets the section — one line:
- `- No ambiguity: <why the request answers itself>`.
+ ## After the go, the window is CLOSED
+ Every question is asked BEFORE the first spawn. If a genuine unknown
+ appears anyway, STOP: hold the work, ask the user, append the answer
+ under `## Clarified`, and name it a clarify MISS in the close report —
+ the signal that the scan or the read was too narrow.
+
## Red flags
| Thought | Reality |
|---------|---------|
| "I get the gist, I'll start" | The gist is the part you already knew. The ambiguity is the rest. |
| "I'll infer it from the code" | Code shows what IS, never what they WANT. |
- | "Asking looks slow" | One question costs a message. A wrong build costs the session. |
- | "I'll ask all four at once" | Answer 2 changes question 3. Batching guesses the order. |
- | "They said go, so it's clear" | "Go" approves a direction, not every detail. |
- | "It's a small change" | A small change on a wrong assumption is still wrong. |
+ | "I'll write it as an assumption" | An assumption is a question you chose not to ask. Ask it. |
+ | "Asking looks slow" | One round costs a message. A wrong build costs the session. |
+ | "I'll ask when I get there" | You get there with three workers running. Ask before the go. |
| "The worker will figure it out" | Workers cannot reach the user. Your ambiguity becomes their guess. |
- | "Nothing here is ambiguous" | Then write that line under `## Clarified` and move — the section is never skipped. |
+ | "Nothing here is ambiguous" | The branch question is still asked and recorded — the section is never empty. |