Clarify

Clarify

Detect and reduce ambiguity or missing decision points in a document, then record clarifications directly back into it.

When to Use

• User has a spec, requirements doc, PRD, design brief, or similar document with gaps
• User wants to tighten up a document before handing it off to implementation
• User says "clarify", "review for gaps", "what's missing", "tighten this spec", etc.
• User uploads or points to a document and wants it stress-tested for completeness

User Input

The user provides:

1. A document to clarify — either uploaded, pasted, or referenced by path.
2. Optional context — e.g., "this is for a mobile app", "we're a 3-person team", "focus on security".

If no document is provided, ask the user to supply one before proceeding.

---

Execution Steps

1. Load the Document

• If the user gave a path, read from that path using the Read tool.
• If the user pasted content, work with that directly.
• Identify the file format (Markdown, plain text, etc.) and preserve it throughout.

2. Ambiguity & Coverage Scan

Perform a structured scan of the document using this taxonomy. For each category, mark status as Clear, Partial, or Missing. This produces an internal coverage map used for question prioritization — do not output the raw map unless no questions will be asked.

Functional Scope & Behavior:

• Core user goals & success criteria
• Explicit out-of-scope declarations
• User roles / personas differentiation

Domain & Data Model:

• Entities, attributes, relationships
• Identity & uniqueness rules
• Lifecycle / state transitions
• Data volume / scale assumptions

Interaction & UX Flow:

• Critical user journeys / sequences
• Error / empty / loading states
• Accessibility or localization notes

Non-Functional Quality Attributes:

• Performance (latency, throughput targets)
• Scalability (horizontal/vertical, limits)
• Reliability & availability (uptime, recovery expectations)
• Observability (logging, metrics, tracing signals)
• Security & privacy (authN/Z, data protection, threat assumptions)
• Compliance / regulatory constraints

Integration & External Dependencies:

• External services/APIs and failure modes
• Data import/export formats
• Protocol / versioning assumptions

Edge Cases & Failure Handling:

• Negative scenarios
• Rate limiting / throttling
• Conflict resolution (e.g., concurrent edits)

Constraints & Tradeoffs:

• Technical constraints (language, storage, hosting)
• Explicit tradeoffs or rejected alternatives

Terminology & Consistency:

• Canonical glossary terms
• Avoided synonyms / deprecated terms

Completion Signals:

• Acceptance criteria testability
• Measurable Definition of Done indicators

Misc / Placeholders:

• TODO markers / unresolved decisions
• Ambiguous adjectives ("robust", "intuitive") lacking quantification

For each category with Partial or Missing status, generate a candidate question unless:

• Clarification would not materially change implementation or validation
• Information is better deferred to a later phase (note internally)

3. Generate Prioritized Question Queue

Produce (internally) a prioritized queue of clarification questions. The number of questions is adaptive — scale to the document's size and ambiguity level:

• Small/clear documents (few gaps): 1–3 questions may suffice.
• Medium documents (moderate gaps): 5–8 questions typical.
• Large/ambiguous documents (many gaps across categories): 10+ questions are appropriate.

There is no hard cap. Ask as many questions as needed to resolve all material ambiguities. Quality over brevity — do not skip a high-impact question to stay under an arbitrary limit.

Constraints:

• Every question MUST provide 2–4 concrete options. The user always has an automatic "Other" free-text fallback, so open-ended questions still work — just provide your best-guess options as starting points.
• Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
• Category coverage balance: cover the highest-impact unresolved categories first; avoid two low-impact questions when a single high-impact area is unresolved.
• Exclude questions already answered in the document, trivial stylistic preferences, or execution-level details.
• Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
• Prioritize by (Impact x Uncertainty) heuristic — highest first.

4. Sequential Questioning Loop (Interactive)

Present questions using the AskUserQuestion tool. This provides a structured UI with selectable options and an automatic "Other" free-text fallback.

For each question, call AskUserQuestion with these required fields:

• question — the full question text, ending with ?.
• header — short category label, max 12 chars (e.g., "Scope", "Data Model", "Auth", "Edge Cases").
• options — 2–4 options, each with label (1–5 words) and description (reasoning/tradeoff). The tool auto-adds an "Other" free-text option, so do not include one manually.
• multiSelect — always false (clarification questions are single-choice).

Recommendation: Place the recommended option first and append (Recommended) to its label.

After the user answers:

• Record the answer in working memory and move to the next queued question.
• If the answer is ambiguous, ask a single follow-up disambiguation (does not count as a new question).

Batching: When questions are independent, batch up to 4 into a single AskUserQuestion call. Only batch when answers to earlier questions do not affect later ones.

Stop asking when:

• All material ambiguities are resolved, OR
• User signals completion ("done", "good", "no more", "stop", "proceed").