Clarify

Clarify

Contract

Inputs

• Scan target, in strict precedence: an explicit argument (clarify <text-or-path>), else the most recent user request when it reads as a spec or task, else the open conversation context. No other input is required; the text-or-path argument is optional.

Procedure

1. Select the target by the precedence above and read it once for the whole run. Done when: the target is selected and read once.
2. Restate the read before scanning: write the target back as a single paraphrased instruction, including what it does not ask for, and compare it against the target. A mismatch is the first finding and outranks every other finding, because a correct answer to a misread request is still wrong. When the restatement matches, carry it silently — it becomes output only if a fork survives. Done when: the restatement is written and compared, and any mismatch is surfaced as the first finding.
3. Pre-scan facts before surfacing anything to the user: resolve every ambiguity that is actually an environmental or codebase fact by direct lookup (search, read, or a subagent) — never ask the user for something the repo can answer. Each resolved fact is recorded as tier auto with its basis, reported compactly, and never becomes a question. Done when: every resolvable-by-lookup ambiguity is resolved as tier auto with its basis.
4. Classify every remaining finding with exactly one certainty tier:
   • auto — an unambiguous project convention resolves it; record the resolution and basis, then proceed.
   • gated — a reasonable default exists; surface it as a recommendation that locks unless the user overrides it.
   • manual — evidence cannot settle genuine intent; surface a non-locking recommendation based on the least irreversible standard choice, then ask.
   • fyi — worth noting, not worth blocking on; list it, never ask. Done when: every remaining finding has exactly one certainty tier assigned.
5. Enforce MECE before emitting: merge or drop findings that ask the same thing as, or overlap, another finding. Done when: the finding set is MECE with no overlaps.
6. Emit the findings report (see Output). The report is the deliverable; the user overrides only the gated/manual rows they disagree with. Done when: the findings report is emitted grouped by tier with manual last.
7. Ask only the manual tier: one single-select question per manual finding with its non-locking recommendation marked, at most four questions per fire. At zero manual findings, ask nothing — the report alone is the result. Done when: manual questions are fired (at most four) or zero manual findings means no questions.
8. After the user's overrides, re-scan the target once; stop when the re-scan adds no new manual finding. Record every settled finding as overridden, answered, or discharged as a non-issue with a one-line reason. Done when: the re-scan adds no new manual finding, and every settled finding is recorded.
9. List any project-specific term the user settled during clarification as a CONCEPTS.md candidate in the report. Record the candidate; write no files. Done when: settled terms are recorded as CONCEPTS.md candidates.

Failure and recovery

• No identifiable target after one read of the context: stop and ask exactly one question naming what to scan. Classify nothing and emit no report; scanning nothing is a failure, not an empty result.
• A fact lookup fails or is inconclusive: the ambiguity is not auto; it falls to normal tiering (usually manual). Never guess a fact to avoid asking.
• Partial scan (a span is unreadable or unreachable): emit the findings found so far, name the span excluded, and do not claim done.
• Manual questions left unanswered: the open manual findings remain; state that clarification is incomplete and list their ids. The done predicate does not hold.
• Nothing is ever written, so there is no rollback: recovery is re-running the scan. Never swallow a lookup error or present an incomplete pass as done.

Output

A findings report grouped by tier with manual last, one block per finding with fields id, quote (the exact ambiguous span), tier, recommendation (— for fyi), and basis (the fact or convention supporting it); gated recommendations marked locked-unless-overridden, manual ones non-locking, auto resolutions appearing compactly with their basis; the manual questions fired (at most four per fire) and the CONCEPTS.md candidates recorded from settled terms; on explicit request for structured output, one fenced clarify-findings/v1 block containing a YAML list of the per-finding fields.