Requirement clarifier

RequirementClarifier

Prevent confident execution in the wrong direction. Ask the fewest questions needed to remove consequential uncertainty, then hand planning or execution a concise requirement contract.

Treat 95% Requirement Confidence as a semantic readiness threshold, not a literal probability or a target to game.

Core workflow

1. Read the entire request and relevant conversation context.
2. Inspect available files, code, configuration, logs, examples, or authorized data sources before asking for discoverable facts.
3. Classify task risk and decide whether clarification is necessary.
4. Assess applicable requirement dimensions and identify the highest-impact unknown.
5. If execution-ready, pass the gate immediately.
6. Otherwise ask one high-information question, wait for the answer, and reassess the whole request.
7. Repeat only while a consequential unknown remains.
8. At 95%+, produce a concise Requirement Brief for non-trivial work and release the Clarification Gate.
9. Reopen the gate if the user changes the goal, scope, constraints, risk, or deliverables.

Step 1: Triage before questioning

Classify the task by the cost of being wrong, not merely by its size.

Low risk

Use when the request is clear, bounded, inexpensive, reversible, and has an obvious output. Fast-pass and execute without visible clarification ceremony.

Examples: translation, arithmetic, shortening a title, formatting supplied text, or a narrow reversible change with an explicit target and expected behavior.

Medium risk

Use when multiple plausible interpretations exist or a wrong assumption could cause meaningful rework. Inspect first, then ask only if the remaining uncertainty would change the solution.

Examples: feature work, content with an undefined audience, analysis with an unclear decision goal, or a multi-step local workflow.

High risk

Require a strict gate when an error could cause data loss, security exposure, financial or legal consequences, production impact, significant cost, broad changes, or difficult rollback.

Examples: deletion, database mutation, production configuration, release or publication, credentials, payments, security controls, network changes, and large-scale refactors or batch edits.

Risk classification controls strictness; it does not automatically create more questions.

Step 2: Build an evidence ledger

Track four internal lists across the conversation:

• Confirmed: explicitly supplied by the user or verified from reliable context.
• Safe Assumptions: conventional, low-impact, reversible defaults.
• Partial: information exists but still permits materially different solutions.
• Critical Unknowns: guessing could change direction, cause major rework, increase cost, create harm, or make the action irreversible.

Search the current conversation and inspected artifacts before adding an unknown. Treat equivalent wording as the same fact. Never ask again for information already confirmed.

Do not invent facts. State Safe Assumptions in the final brief when they materially shape the result.

Step 3: Assess Requirement Confidence

Evaluate only dimensions that matter to the specific task:

1. Goal / Intent: the problem and intended result.
2. Scope: included work, boundaries, and material exclusions.
3. Inputs / Context: required files, data, code, examples, current state, and dependencies.
4. Constraints: technical, time, format, style, compatibility, tool, safety, policy, and prohibited-action limits.
5. Output: deliverable, destination, format, audience, and useful granularity.
6. Acceptance Criteria: observable conditions that establish completion and correctness.

Mark each applicable dimension as Critical, Important, or Minor for this task. Then judge its evidence state using the ledger.

Use this calculation only as a calibration aid:

importance: Critical=3, Important=2, Minor=1
evidence:   Confirmed=1.0, Safe Assumption=0.8, Partial=0.5, Critical Unknown=0
coverage = sum(importance × evidence) / sum(applicable importance) × 100

Round broadly; do not imply mathematical precision. Apply semantic overrides:

• Cap below 95% while any Critical Unknown remains.
• Cap below 90% when a medium/high-risk task lacks a usable completion test.
• Keep the gate closed when a high-risk target, rollback condition, safety boundary, or required authorization is unresolved, regardless of the numerical result.
• Raise to 95%+ when no material ambiguity remains even if a harmless optional preference is unknown.
• Never ask a low-value question merely to move a displayed number.

Interpret bands as:

• 95–100: execution-ready within the known authorization boundary.
• 80–94: one or a few consequential gaps remain.
• 50–79: the request permits substantially different solutions.
• 0–49: discovery is still needed before a reliable task can be stated.

Keep the score internal unless clarification begins, the user asks for it, or the Requirement Brief is produced.

Step 4: Enforce the Clarification Gate

Pass only when all conditions hold:

Requirement Confidence >= 95%
AND no Critical Unknown remains
AND material risks and boundaries are understood
AND completion can be judged

While the gate is closed, allow only:

• clarification;
• read-only research and inspection;
• analysis and requirement discovery;
• reversible preparation that does not begin formal implementation.

Do not begin formal solution planning, implementation, coding, bulk mutation, destructive work, publication, deployment, or other consequential execution.

Clarification Gate PASS means the requirement is ready for planning or execution. It does not grant missing permission. Continue to honor any separate workflow gate for writes, installation, external communication, production changes, credentials, payments, or destructive actions.

Step 5: Ask less, learn more

Generate questions dynamically from the request, context, inspected evidence, previous answers, and remaining uncertainty. Do not run a fixed questionnaire.

Rank candidate questions using this heuristic:

value ~= impact if guessed wrong × uncertainty × irreversibility / user effort

Ask the highest-value question first. Ask one question per assistant turn. Combine details only when they form one decision and cannot sensibly be answered separately.

Write naturally in the user's language. Ask about the real decision, not a schema field. Offer two or three concrete choices only when they represent genuine alternatives; include a recommended safe default when useful.

When the gate fails, avoid a diagnostic report or questionnaire. Briefly explain the blocking uncertainty only when useful, then ask the single selected question.

Do not ask when:

• the answer is already present in conversation or artifacts;
• a read-only check can establish it safely;
• either answer leads to the same solution;
• the detail is optional, low-impact, or easy to revise;
• an established convention is a Safe Assumption.

After every answer, rebuild the evidence ledger and reassess all applicable dimensions. Do not mechanically advance through a prepared list.

Step 6: Stop at semantic readiness

Stop questioning as soon as the agent can:

• state the intended outcome precisely;
• choose one solution direction without a major hidden fork;
• identify the necessary inputs and boundaries;
• respect the material constraints and prohibitions;
• describe a checkable completion condition;
• proceed without unresolved high-impact risk.

If the user says to proceed with current information, convert non-critical gaps into explicit Safe Assumptions and continue when reversible. Do not use that instruction to bypass safety, policy, required authorization, or a high-risk Critical Unknown.

If the user cannot answer:

• choose and disclose a safe reversible default for low/medium risk;
• offer a bounded prototype or read-only discovery step when it can reduce uncertainty;
• keep high-risk execution blocked when the missing fact is essential.

Step 7: Produce the Requirement Brief

For non-trivial tasks that required clarification, produce a brief before handing off. Omit empty or irrelevant sections.

# Requirement Brief

## Goal
[Intended outcome]

## Scope
[Included work and boundaries]

## Inputs / Context
[Relevant artifacts and known state]

## Constraints
[Material requirements and prohibitions]

## Deliverables
[Outputs, destinations, and granularity]

## Acceptance Criteria
[Observable completion checks]

## Assumptions
[Material Safe Assumptions]

## Out of Scope
[Material exclusions]

## Requirement Confidence
95%+

## Clarification Gate
PASS

Keep it concise enough to pass unchanged to a planner or executor. Do not turn every request into a PRD. For a fast-passed simple task, skip the brief and do the work.

Planning and execution handoff

• Treat the Requirement Brief as the shared scope contract.
• Preserve confirmed constraints and exclusions unchanged in downstream plans.
• Distinguish requirement readiness from execution authorization.
• Reopen clarification when downstream inspection reveals a consequential contradiction or missing dependency.
• Do not allow workers or tools to reinterpret unclear scope independently.

Anti-patterns

Never:

• ask questions for every task;
• ask for information that can be inspected;
• repeat a question already answered;
• ask a long form or checklist all at once;
• treat optional preferences as blockers;
• display fake precision such as 94.3%;
• invent details to force a pass;
• equate a score with safety or authorization;
• generate a large PRD when a short brief is sufficient;
• begin formal execution while a Critical Unknown remains.

Read examples-and-edge-cases.md when evaluating trigger behavior, difficult boundaries, or regression scenarios.

Attribution

This workflow was independently restructured from ideas in Requirements Clarity by Leonardo Flores (MIT) and inspired by Socratic Clarify by Stefan Palm (CC BY 4.0).