Skip to content

request-clarification-loop.md

Latest commit

 

History

History
182 lines (113 loc) · 5.25 KB

request-clarification-loop.md

File metadata and controls

182 lines (113 loc) · 5.25 KB

Request Clarification Loop

Purpose

Help an agent turn a messy user request into an execution-ready brief before tools, bash commands, or file edits begin.

This workflow exists to make the user feel:

  • understood before action
  • guided but not interrogated
  • in control of what the agent is trying to do

When To Use

Use this workflow when:

  • the request is broad, vague, or underspecified
  • the intended deliverable is unclear
  • the task may branch in several reasonable directions
  • execution could waste time or create risk if the guess is wrong

Do not overuse it.

If the request is already clear and low-risk, summarize the task and proceed.

Main Rule

Ask fewer questions, but make each one carry weight.

The goal is not to extract every detail.

The goal is to remove the highest-risk ambiguity before execution starts.

Output Contract

Before execution, the agent should produce:

  1. a short restatement of the user's request
  2. the main ambiguity or missing context
  3. 1-3 reverse questions
  4. a provisional brief based on current understanding

Step 1. Restate The Request

Rewrite the user's request in plain language.

This restatement should:

  • preserve the user's intent
  • make the deliverable more concrete
  • surface the likely job to be done

Good pattern:

  • My understanding is that you want X so that Y.

Avoid:

  • repeating the user's words without clarification
  • adding assumptions as if they were confirmed facts

Step 2. Identify The Highest-Risk Unknown

Do not list every possible missing detail.

Find the one thing most likely to cause the agent to do the wrong work.

Common high-risk unknowns:

  • wrong deliverable type
  • wrong audience
  • wrong level of depth
  • wrong success criteria
  • wrong source material or working scope
  • hidden safety constraints

Step 3. Ask 1-3 Reverse Questions

Reverse questions should narrow direction, not create homework.

Each question should do one of these jobs:

  • choose between plausible paths
  • define the deliverable shape
  • reveal an important constraint

Good reverse question patterns:

  • Should this end as a summary, a draft, or an action plan?
  • Is your main goal speed, completeness, or safety?
  • Should I work only with the files already here, or also propose outside references?
  • Is this something you want me to execute now, or first shape into a plan you can review?

Bad reverse question patterns:

  • asking for information that can be inferred locally
  • asking too many setup questions at once
  • asking broad questions like Can you give more context?
  • asking questions whose answers will not change the work

Step 4. Build A Provisional Brief

Do not wait for perfect certainty.

After the reverse questions, produce a provisional brief that states:

  • objective
  • expected output
  • constraints
  • assumptions currently being made
  • what will happen next after confirmation

Good pattern:

  • Provisional brief: I will prepare X for Y audience, using Z scope, assuming A unless you want a different direction.

Step 5. Pause Before Execution

If the task may lead to tool use, shell commands, edits, or external actions, pause after the brief and wait for confirmation when needed.

This matters most when:

  • the request involves uncertainty plus risk
  • the agent may modify files
  • the agent may run bash commands the user did not explicitly ask for

Decision Heuristic

Use this quick rule:

  • clear and low-risk: restate briefly and proceed
  • unclear but low-risk: ask 1-2 reverse questions
  • unclear and medium/high-risk: ask up to 3 reverse questions and provide a provisional brief before acting

Tone Rules

The workflow should feel collaborative, not bureaucratic.

Prefer:

  • To make sure I aim at the right target...
  • Before I run with this, I want to pin down one thing.
  • Here is my current read, and the one choice that matters most.

Avoid:

  • Please provide more context.
  • I need additional information before proceeding.
  • long question lists that make the user do discovery work alone

Review Checklist

Before moving past clarification, check:

  • does the user likely feel understood?
  • is the deliverable shape now clear?
  • did the questions materially reduce ambiguity?
  • did we avoid unnecessary back-and-forth?
  • are assumptions stated explicitly?

Example

User request:

이거 정리해서 팀에 보낼 수 있게 해줘

Weak response:

  • 어떤 형식으로 원하시나요? 대상은 누구인가요? 길이는 어느 정도인가요? 언제까지 필요한가요?

Better response:

  • 제 이해는, 지금 있는 내용을 팀에 공유 가능한 형태로 정리해달라는 요청이에요. 여기서 가장 중요한 건 결과물이 "짧은 공유 메모"인지 "의사결정용 문서"인지예요. 팀에 바로 보낼 짧은 정리본으로 만들까요, 아니면 배경과 추천안까지 들어간 문서로 만들까요?
  • Provisional brief: 팀 공유용 문서를 만들되, 우선 짧고 바로 전달 가능한 형태를 기본값으로 잡겠습니다. 원하시면 그다음 단계에서 의사결정용 확장본으로 키울 수 있어요.

Success Condition

This workflow is successful if the user feels:

  • 내 요청을 제대로 이해했네
  • 질문이 많지 않은데 중요한 걸 잘 짚네
  • 이제 실행해도 방향이 맞을 것 같아