Disclose Ambiguity

Intent

Prompt the model to list the assumptions inherent in your prompt, or missing information that’s needed to complete your task, and describe its resolution—or ask you for input.

Motivation

Software engineers spend significant time on discovering and resolving ambiguities in software requirements and design. Whether you take a documentation-heavy approach in which you create detailed specification documents, or an iterative approach based on incrementally exploring a potential solution with stakeholders, a big part of the software engineering process focuses on converting imprecise statements in written or spoken language into precise instructions that a computer follows. Another big part focuses on discovering whether the decisions you and your collaborators make in this process result in a product that satisfies your customers’ expectations, and adapting the software to address any divergences.

When you prompt a coding assistant to generate source code, the model’s completion bias causes it to work towards finishing your prompted task, even if the requirements you give it are incomplete or ambiguous. You can expect your prompt to be an incomplete specification of the task you prompt the agent to complete, but you should choose whether the agent fills in the gaps and, if so, You Review what it does.

Apply Disclose Ambiguity to uncover the hidden choices in your instructions to your coding assistant, and whether the assistant generates code that encodes a particular assumption about the ambiguous output. Choose the correct approach for the assistant to follow, or involve relevant stakeholders in the decision.

Applicability

Use Disclose Ambiguity before prompting a coding assistant to implement a specification, to uncover unresolved decisions and refine your prompt, potentially in conversation with other stakeholders. Apply the pattern after the assistant completes a task, so the Model Reviews the generated output and discovers features in the code that represent tacit refinements of the problem description you provided as a prompt.

You can use Disclose Ambiguity in two ways:

• Fix Forward. Identify issues caused by unstated assumptions in your prompt or solution requirements, and address them in implementation.
• Back track. Discover ambiguities in your prompt or requirements and correct the documents before you proceed to use them in implementation.

Consider combining Disclose Ambiguity with Remember What we Did to produce a decision record.

Consequences

Disclose Ambiguity offers the following benefits:

• Identify tacit assumptions or points of ambiguity in your prompts and designs.
• Initiate conversations with customers and other stakeholders to resolve discovered issues.
• Discover divergence between your expectations and the model's output before implementation.

Implementation

Prompt the coding assistant to Disclose Ambiguity by adding instructions before or after your task description, for example:

Don't actually perform this task. Instead, identify ambiguities in the description or assumptions you would have to make to follow the instructions, and report the issues to the user.

In an interactive session, instruct the assistant to ask you how to resolve the ambiguities, and use your answer to update your prompt or design document.

Many coding assistants include a tool called ask_user_question or AskUserQuestion that the agent uses to present a question and a menu of potential answers that you choose from.

Examples

Rescuing Spec-Driven Development

The common Spec-Driven Development approach to AI-augmented software development relies on taking Baby Steps when generating code from an initial prompt, by turning the initial prompt into a specification of the software, turning the specification into a list of tasks, and then turning the tasks into code. At each of these steps, the assistant might introduce output that’s consistent with the problem statement, but not with your expectations of the result, due to ambiguities or unstated assumptions in your prompt.

Apply Disclose Ambiguity at each stage of the Spec-Driven Development process to discover and address these issues early, instead of waiting until You Review the generated software. For example, sending this prompt to Claude Sonnet 4.6 in Claude Code encourages it to Disclose Ambiguity in an initial description of a software solution:

Don't actually perform the following instructions for the moment. Instead, identify any ambiguities or unstated assumptions in the problem statement, and ask the user how to resolve them. Update the problem statement to incorporate the user's answers, and write the updated version to a markdown file.

Create user stories to guide the implementation of a web-based DJ application. The user can choose music files to load into two players in their browser window. Each player has separate play, pause, volume, and EQ controls. The app multiplexes the output from both players.

The assistant initially creates the file with the ambiguities noted.

# MiniDJ Web App — User Stories

## Epic: Music File Loading

- As a DJ, I want to open a local music file into Player 1, so that I can prepare the next track.
- As a DJ, I want to open a local music file into Player 2, so that I can have two tracks ready simultaneously.
AMBIGUITY: Should file loading support only local files via the browser's file picker, or also URLs/streaming sources?

## Epic: Playback Controls

- As a DJ, I want to play and pause each player independently, so that I can control when each track is heard.
- As a DJ, I want to see the current playback position of each track, so that I know where I am in the music.
AMBIGUITY: Should there be a seek/scrub control (e.g. a progress bar the user can drag) on each player?
AMBIGUITY: Should there be waveform visualisation for each track?

## Epic: Volume Controls

- As a DJ, I want to adjust the volume of each player independently, so that I can balance the levels of the two tracks.

## Epic: EQ Controls

- As a DJ, I want EQ controls on each player, so that I can shape the sound of each track.
AMBIGUITY: What kind of EQ? Options: (a) simple 3-band (bass/mid/treble), (b) parametric with adjustable frequency and Q, (c) graphic EQ with more fixed bands. DJ mixers typically use 3-band kill EQs.

## Epic: Output Mixing

AMBIGUITY: What does "multiplexes the output" mean in practice? Options: (a) both players mix simultaneously into a single stereo output (simple summing mixer), (b) a crossfader control that blends between the two players, (c) the ability to route each player to a separate output channel.
- As a DJ, I want the audio from both players to be combined into a single output, so that my audience hears both tracks.

## Epic: Output Routing

AMBIGUITY: Should the user be able to select the audio output device (e.g. for a DJ setup with a separate monitor/headphone cue channel), or is outputting to the browser's default audio device sufficient?
AMBIGUITY: Should the app support recording or exporting the mixed output?

## Epic: BPM and Sync

AMBIGUITY: Should the app include any BPM detection, tempo display, or sync/beatmatch features, or is this out of scope for the initial version?

This source file is available at user-stories-ambiguous.md.

It then asks about each of the ambiguities, for example:

What does "multiplexes the output from both players" mean for this app?

  1. Simple mix
     Both players play simultaneously and their audio is summed into a single
     stereo output. Volume knobs on each deck control the blend.
  2. Crossfader
     A crossfader control blends between the two players, like a traditional DJ
     mixer. Volume controls are also present per deck.
  3. Separate outputs
     Each player can be routed to a different audio output device (e.g. one to
     speakers, one to headphones for cueing).
  4. Type something.
  5. Chat about this

When someone supplies answers to all questions, the assistant rewrites the document with the ambiguities resolved:

# MiniDJ Web App — User Stories

## Scope & Decisions

- Two independent decks (Player 1 and Player 2), each with play/pause, volume, and 3-band EQ (bass/mid/treble).
- A crossfader blends the output of the two decks into a single stereo mix played through the browser's default audio output.
- MVP only: no waveform display, no seek/scrub, no BPM detection, no loop controls, no recording.
- Music files are loaded from the user's local filesystem via the browser file picker.

---

## Epic: Music File Loading

- As a DJ, I want to open a local music file into Deck 1 using a file picker, so that I can load a track onto the first deck.
- As a DJ, I want to open a local music file into Deck 2 using a file picker, so that I can load a track onto the second deck.
- As a DJ, I want to see the name of the loaded track displayed on each deck, so that I know which track is cued up.

## Epic: Playback Controls

- As a DJ, I want to press Play on a deck to start playback of its loaded track, so that the track begins playing.
- As a DJ, I want to press Pause on a deck to pause playback at the current position, so that I can hold the track without losing my place.
- As a DJ, I want playback to stop at the end of a track rather than looping, so that I know when the track has finished.

## Epic: Volume Controls

- As a DJ, I want a volume fader on each deck, so that I can control the individual gain of each track independently of the crossfader.

## Epic: EQ Controls

- As a DJ, I want a Bass knob on each deck, so that I can boost or cut the low frequencies of that track.
- As a DJ, I want a Mid knob on each deck, so that I can boost or cut the mid frequencies of that track.
- As a DJ, I want a Treble knob on each deck, so that I can boost or cut the high frequencies of that track.
- As a DJ, I want each EQ band to have a centre/flat position, so that I can reset a band to neutral.

## Epic: Crossfader

- As a DJ, I want a crossfader between the two decks, so that I can blend smoothly from one track to the other.
- As a DJ, I want the crossfader at the far left to output only Deck 1, so that I can isolate the first track.
- As a DJ, I want the crossfader at the far right to output only Deck 2, so that I can isolate the second track.
- As a DJ, I want the crossfader at the centre to mix both decks at equal level, so that both tracks are heard simultaneously.

## Epic: Audio Output

- As a DJ, I want the mixed output from both decks (after the crossfader) to play through the browser's default audio output, so that my audience hears the mix.

The source file is available at user-stories-disambiguated.md.

Ambiguity-Resolution Skill

This markdown prompt defines an agent skill that causes a coding assistant to Disclose Ambiguity:

---
name: ambiguity-resolution
description: Resolve design ambiguities
license: AGPL-3.0-or-later
user-invocable: true
allowed-tools:
 - read_file
 - write_file
 - search_replace
 - ask_user_question
---
# Ambiguity Resolution Skill

This skill helps you identify design ambiguities, and resolve them with the user's input.

Given a design document or a specification, identify conflicts in the requirements or design, or ambiguities in the requirements statement, by searching the document for instances of the word CONFLICT or AMBIGUITY. For each instance that you find, ask the user how to resolve the conflict or ambiguity. Use the user's answer to update the document, and remove the original conflict/ambiguity statement from the document.

The file examples/process.md shows an example in a process document.

The source file is available at SKILL.md.

Store this file in ~/.agent/skills/ambiguity-resolution/SKILL.md. Use the slash command /ambiguity-resolution in a coding assistant that supports skills, for example Claude Code or Mistral Vibe, to prompt the agent to Disclose Ambiguity. Alternatively, the agent discovers it has access to the skill, and initiates Disclose Ambiguity when ambiguities arise.

Related Patterns

Remember What We Did to record decisions you take when resolving ambiguities.

You Review to find other issues that the model doesn’t report.

Defer the Details when the assistant asks a question you don’t need to answer yet.