Ambiguous Requirement Clarification Prompt

This prompt is for BDD practitioners, product owners, and QA leads who are staring at a user story or feature brief that feels 'almost ready' but collapses under scrutiny. The job-to-be-done is not to generate acceptance criteria yet—it is to surface the hidden assumptions, missing actors, and silent failure modes that will cause rework later. Use this prompt when a requirement contains vague adjectives ('fast', 'secure', 'intuitive'), when the happy path is clear but error states are invisible, or when multiple stakeholders interpret the same sentence differently. The ideal user is someone who can recognize that a requirement is underspecified but needs a structured, ranked list of questions to drive a productive clarification session with the product trio.

Do not use this prompt when the requirement is already formalized as a detailed technical specification with defined error codes, when you need executable Gherkin immediately (use the User Story to Gherkin Scenario Prompt instead), or when the ambiguity is purely about UI layout rather than system behavior. This prompt is also a poor fit for trivial feature tweaks where the cost of a clarification meeting exceeds the cost of getting the implementation slightly wrong. The output is a structured analysis artifact, not a replacement for human judgment—every clarification question should be reviewed by someone who understands the domain context and can distinguish between a genuine implementation risk and a theoretical edge case with no user impact.

Before running this prompt, gather the raw requirement text, any supporting documents (PRD sections, user research snippets, dependency diagrams), and a list of known constraints such as regulatory requirements, performance SLAs, or legacy system limitations. Feed these into the [REQUIREMENT] and [CONTEXT] placeholders. After receiving the output, use the ranked clarification questions to drive a focused session with engineering, product, and design. Resolve each question before proceeding to acceptance criteria generation. If the model flags a risk you believe is irrelevant, document the dismissal reason—this becomes part of the requirement's audit trail and protects against future assumptions.

This template is the core of the Ambiguous Requirement Clarification playbook. It is designed to take a raw or partially defined requirement and force the model to act as a disciplined BDD analyst. The prompt instructs the model to identify what is unsaid, rank those gaps by the risk they pose to implementation, and propose concrete resolution paths. You can copy this template directly into your prompt library, replace the square-bracket placeholders with your specific inputs, and run it against a new requirement before any Gherkin scenarios are written.

textCopy
You are a senior BDD analyst and QA architect. Your task is to review a product requirement and identify hidden assumptions, ambiguities, and missing details that would prevent writing executable acceptance criteria.

## INPUT
Requirement text:
[REQUIREMENT_TEXT]

Supporting context (user story, PRD excerpt, or system notes):
[CONTEXT]

## CONSTRAINTS
- Do not solve the requirement or write acceptance criteria.
- Do not ask questions that are already answered in the requirement or context.
- Focus on gaps that would cause a developer to make an incorrect assumption or a tester to miss a failure condition.
- For each question, explain *why* the answer changes implementation or testing.

## OUTPUT_SCHEMA
Return a JSON object with a single key "clarification_questions" containing an array of objects. Each object must have the following fields:
- "id": string, a short unique identifier (e.g., "CQ-01")
- "category": string, one of ["Data & Boundaries", "Error & Failure Handling", "User & Permissions", "Performance & Scale", "State & Ordering", "Integration & Dependencies", "UX & Copy", "Compliance & Audit"]
- "question": string, the specific clarification question
- "risk_if_unresolved": string, one of ["High", "Medium", "Low"]
- "impact": string, a one-sentence explanation of what breaks or is untestable if this question is not answered
- "suggested_resolution": string, a recommended method to resolve the ambiguity (e.g., "Stakeholder interview", "Review existing API contract", "Legal review", "Performance modeling")

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

To adapt this template, start by populating [REQUIREMENT_TEXT] with the exact language from your ticket, PRD, or user story. The [CONTEXT] field is critical for avoiding redundant questions—paste in any related acceptance criteria drafts, system diagrams, or API docs you already have. The [EXAMPLES] placeholder should be replaced with 1-3 few-shot examples of good clarification questions for your domain, which dramatically improves output quality. The [RISK_LEVEL] field allows you to filter the output by setting a minimum risk threshold (e.g., "Only return questions with risk_if_unresolved equal to High or Medium"). If you are working in a regulated domain, ensure the "Compliance & Audit" category is represented in your examples. After running the prompt, validate the output against the schema before feeding the questions into a stakeholder review session or a downstream Gherkin generation prompt.

This prompt is designed to sit between a raw requirement input and the downstream acceptance criteria or Gherkin scenario generation step. It should be called before any behavior specification work begins. The typical integration point is a product or QA workflow where a user pastes a requirement, user story, or feature brief, and the system returns a structured list of clarification questions ranked by implementation risk. The output is not the final artifact—it is a decision-forcing artifact that must be reviewed by a human before the next prompt in the chain executes.

Validation and output contract. The prompt template includes an [OUTPUT_SCHEMA] placeholder that should be replaced with a strict JSON schema. Each clarification question must include: id, question, risk_level (enum: blocker, high, medium, low), category (enum: ambiguity, missing_actor, missing_constraint, conflict, undefined_edge_case, assumption), suggested_resolution_path, and source_quote from the original requirement text. Validate the model response against this schema before surfacing it. Reject any output where risk_level: blocker questions lack a source_quote or where category values fall outside the enum. If validation fails, retry once with the validation error message appended to the prompt as a [CORRECTION] block. After two failures, surface the raw output to a human reviewer with a flag.

Model choice and latency budget. This is a reasoning-heavy task that benefits from models with strong instruction-following and structured output capabilities. GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are appropriate defaults. Expect 5–15 seconds of latency for a typical requirement paragraph. Do not use a small or quantized model for this prompt unless you have calibrated eval scores against a human-annotated baseline. If latency is a concern, set a 30-second timeout and fall back to a cached set of generic clarification categories with a note that automated analysis was incomplete.

Human review and escalation. Every output from this prompt must pass through a human review step before downstream acceptance criteria generation begins. The review UI should display each question with its risk level, category, and source quote, and allow the reviewer to accept, edit, dismiss, or add questions. Track which questions were dismissed and why—this data is gold for improving the prompt's precision over time. For regulated or safety-critical domains (healthcare, finance, aviation), require a second reviewer sign-off on any blocker questions that were dismissed. Log the full prompt, response, validation result, and reviewer actions for auditability.

Downstream integration. Once the clarification questions are reviewed and resolved, feed the original requirement plus the resolved clarifications into a follow-up prompt such as the User Story to Gherkin Scenario Prompt Template or the Edge Case Discovery Prompt for Acceptance Criteria. The resolved clarifications should be injected as a [RESOLVED_ASSUMPTIONS] block so the downstream prompt has explicit context rather than repeating the same ambiguity. Do not skip the clarification step and go straight to Gherkin generation—the whole point of this prompt is to catch the ambiguities that cause acceptance criteria to be rewritten three sprints later.

What to avoid. Do not treat this prompt as a one-shot magic box. If the input requirement is a single vague sentence, the output will be a long list of low-value questions that frustrate reviewers. Set a minimum input quality bar: the requirement should contain at least an actor, an action, and an outcome before this prompt is invoked. If the input fails that bar, return a polite message asking the user to expand the requirement rather than generating 40 clarification questions. Also avoid chaining this prompt directly into automated test generation without human review—unresolved ambiguities turn into flaky tests.