Ambiguity Detection & Clarification Generation

Purpose

This skill identifies critical decision gaps in product requirements or PRDs that, if left unresolved, would lead to misalignment, rework, or irreversible downstream mistakes.

It does not resolve ambiguity.
It surfaces it precisely and neutrally as structured clarification questions.

Use this skill as a validation pass before roadmap definition, feature decomposition, or execution planning.

---

When to Use This Skill

Use this skill when you need to:

• Validate whether a PRD or requirement set is decision-complete
• Detect hidden assumptions that affect scope, data ownership, or risk
• Prepare structured clarification questions for stakeholders
• Ensure irreversible or high-impact decisions are made explicitly

Do not use this skill to:

• answer questions
• define defaults
• decide priority or severity
• pause or resume workflows
• rewrite PRDs
• plan implementation or UX

---

Core Principle

If a missing decision could change the shape of the product, it must be surfaced.

This skill favors:

• precision over completeness
• decision-forcing questions over open-ended discussion
• minimal, high-signal outputs

---

What Counts as Ambiguity

Ambiguity is not missing detail.

Ambiguity is unresolved uncertainty that affects:

• product boundaries
• user trust or responsibility
• data authority or mutability
• irreversible workflows
• compliance or risk posture
• success or failure interpretation

If different answers would lead to materially different designs, it is ambiguity.

---

Ambiguity Detection Categories

Evaluate the input strictly across the following categories.

1. User & Actor Ambiguity

Detect uncertainty about:

• primary vs secondary users
• conflicting incentives between actors
• explicitly out-of-scope users or roles

---

2. Scope Boundary Ambiguity

Detect uncertainty about:

• where the product’s responsibility starts and ends
• delegated vs owned behavior
• edge cases at integration boundaries

---

3. Data & State Ambiguity

Detect uncertainty about:

• authoritative data sources
• mutable vs immutable state
• derived vs stored data
• ownership across systems

---

4. Workflow & Control Ambiguity

Detect uncertainty about:

• irreversible actions
• retry or rollback expectations
• partial failure handling
• required vs optional steps

(This is conceptual, not orchestration logic.)

---

5. Risk, Trust & Compliance Ambiguity

Detect uncertainty about:

• regulatory or legal assumptions
• auditability requirements
• security or privacy expectations
• user consent or disclosure boundaries

---

6. Success & Failure Ambiguity

Detect uncertainty about:

• how success is evaluated
• acceptable failure modes
• trade-offs between competing outcomes

---

Question Generation Guidelines

When ambiguity is detected:

• Ask decision-forcing questions
• Avoid leading language
• Avoid implied defaults
• Provide structured options only when they clarify the decision space
• Prefer fewer, higher-impact questions

Bad Question

“Should we handle errors better?”

Good Question

“If an external dependency fails mid-operation, should the system automatically roll back, allow partial completion, or require manual intervention?”

---

Output Format

The output should be Markdown content only, suitable for direct inclusion in a clarification document.

Use the following structure:

# Project Clarifications

> Please review and select options or provide input for each question.

## Q1: [Decision Area]

- [ ] Option A: [Description]
- [ ] Option B: [Description]
- [ ] Other: [Please specify]

## Q2: [Decision Area]
...

Only include options when they meaningfully bound the decision space.

---

Important Boundaries

This skill must not:

• ask the user questions directly
• decide whether execution should pause
• infer or assume answers
• modify or rewrite PRD content
• propose implementation approaches
• create files or trigger tools
• prioritize or rank ambiguities

All orchestration and decision flow belongs to the calling agent.

---

Output Expectations

The output of this skill should be:

• concise and high-signal
• free of speculation
• neutral in tone
• deterministic for the same input
• focused on decisions that materially affect product shape

Assume the output will be reviewed by senior product, engineering, and compliance stakeholders.