Prompt Clarifier

Prompt Clarifier

A skill that converts vague user instructions into structured, agent-optimized prompts through a brief Socratic interview — before any execution begins.

Why This Matters

Vague prompts ("fix the bug", "add auth") produce divergent results because the agent makes arbitrary decisions on scope, constraints, and success criteria. A 2-minute clarification interview eliminates 80% of revision cycles by capturing intent, constraints, and definition of done before any code is written.

When to Invoke

Invoke this skill before any other action when:

• The prompt is under 10 words and contains no file path, error message, or acceptance criteria
• CLARIFIER_ADVISORY appears in your context window
• The user has expressed intent without saying what done looks like

Skip clarification and proceed directly when:

• You can read the relevant files and the intent is unambiguous from codebase context
• The prompt already contains specific file paths, named functions, or error messages
• The prompt is a question (ends with ?)

The 5 Enrichment Dimensions

Every vague prompt is missing coverage across these axes. Your interview targets whichever dimensions have the largest gap:

Interview Protocol

Step 1: Detect missing dimensions

Scan the original prompt. Which of the 5 dimensions are missing or ambiguous? Rank them by impact — missing Intent is worse than missing Context.

Step 2: Ask one question at a time

Pick the highest-impact missing dimension. Ask a single, focused question. Prefer multiple-choice over open-ended:

"Is this about correctness (wrong output), performance (it's slow), or experience (it feels wrong)?" is better than "What's the problem?"

Step 3: Maximum 3 rounds

After 3 questions, enrich with what you have. Don't let the interview become a form. If the user answers briefly, accept it and move on.

Step 4: Produce the enriched prompt

Output the enriched prompt in the XML schema below. Show it to the user and ask: "Should I proceed with this, or is anything off?"

Step 5: Execute against the enriched prompt

On approval (including implicit approval — no objection after 10 seconds), proceed with the enriched prompt as your working specification.

Question Bank

Use these as starting points. Adapt the wording to the context — don't read them verbatim.

For full question guidance, see references/question-bank.md.

Intent questions (ask first for "fix", "improve", "make better" prompts):

• "What's happening now vs. what should happen?"
• "Is this about correctness, performance, or experience?" [multiple choice]

Scope questions (ask first for "add X", "build X" prompts):

• "What existing behavior must stay completely unchanged?"
• "Any edge cases or user types that must be handled?"

Constraint questions (ask for auth, payments, data-handling prompts):

• "Any security or compliance requirements? (e.g., session handling, logging restrictions)"

Success criteria (ask if not answered by Intent):

• "How will you verify this is working? What test or check would satisfy you?"

Context (ask if no file paths mentioned):

• "Which file or component is the starting point? Or should I search the codebase?"

Enriched Prompt XML Schema

ALWAYS use this exact structure for the output:

<enriched_prompt>
  <original_request>[verbatim user prompt]</original_request>

  <intent>
    <what_to_accomplish>[one sentence — the actual goal]</what_to_accomplish>
    <type>bug_fix | new_feature | refactor | performance | ui_improvement | other</type>
    <priority>critical | high | normal</priority>
  </intent>

  <context>
    <entry_point>[file path or component where work starts, or "TBD — search codebase"]</entry_point>
    <affected_systems>[comma-separated affected components]</affected_systems>
  </context>

  <constraints>
    <must_not_break>[existing behaviors, APIs, or tests that must stay intact]</must_not_break>
    <scope_boundary>[what is explicitly out of scope for this task]</scope_boundary>
    <security>[security or compliance requirements, or "none stated"]</security>
  </constraints>

  <success_criteria>
    <criterion>[verifiable outcome #1]</criterion>
    <criterion>[verifiable outcome #2]</criterion>
    <definition_of_done>[how the user will verify the task is complete]</definition_of_done>
  </success_criteria>

  <output_format>
    <deliverable>[what to produce: code change, explanation, PR description, etc.]</deliverable>
  </output_format>
</enriched_prompt>

For the copy-pasteable blank template, see references/enriched-prompt-template.xml.

Examples

Before / After: "add authentication"

Before:

add authentication

After 2 questions ("What auth method — email/password, OAuth, or both?" + "Which routes need protection?"):

<enriched_prompt>
  <original_request>add authentication</original_request>
  <intent>
    <what_to_accomplish>Add email/password login with session persistence so unauthenticated
    users are redirected to /login before accessing protected routes</what_to_accomplish>
    <type>new_feature</type>
    <priority>high</priority>
  </intent>
  <context>
    <entry_point>src/app/(protected)/layout.tsx — gate all protected routes here</entry_point>
    <affected_systems>Next.js app router, Supabase Auth, middleware</affected_systems>
  </context>
  <constraints>
    <must_not_break>Public routes (/, /about, /pricing) must stay accessible without auth</must_not_break>
    <scope_boundary>OAuth providers (Google, GitHub) are out of scope for this iteration</scope_boundary>
    <security>Use httpOnly cookies for session storage. Do not log passwords or tokens.</security>
  </constraints>
  <success_criteria>
    <criterion>Unauthenticated user hitting /dashboard is redirected to /login</criterion>
    <criterion>Authenticated user can log out and session is cleared</criterion>
    <definition_of_done>Manual test: sign up → log in → access protected route → log out → confirm redirect</definition_of_done>
  </success_criteria>
  <output_format>
    <deliverable>Code changes to middleware, new auth pages, Supabase config</deliverable>
  </output_format>
</enriched_prompt>

Before / After: "fix the bug"

Before:

fix the bug

After 2 questions ("What's happening vs. what should happen?" + "Where does the bug occur — which page, action, or API call?"):

<enriched_prompt>
  <original_request>fix the bug</original_request>
  <intent>
    <what_to_accomplish>Fix the checkout form submission that silently fails when the user's
    cart has more than 10 items — no error shown, order not created</what_to_accomplish>
    <type>bug_fix</type>
    <priority>critical</priority>
  </intent>
  <context>
    <entry_point>src/components/CheckoutForm.tsx → handleSubmit function</entry_point>
    <affected_systems>CheckoutForm component, /api/orders route handler, cart state</affected_systems>
  </context>
  <constraints>
    <must_not_break>Existing orders with ≤10 items must continue to work</must_not_break>
    <scope_boundary>Cart pagination and bulk discount logic are out of scope</scope_boundary>
    <security>none stated</security>
  </constraints>
  <success_criteria>
    <criterion>Submitting a cart with 11+ items creates an order successfully</criterion>
    <criterion>If the order fails, the user sees a clear error message</criterion>
    <definition_of_done>Add a cart with 11 items, submit checkout, confirm order appears in the DB</definition_of_done>
  </success_criteria>
  <output_format>
    <deliverable>Bug fix in CheckoutForm.tsx and/or the orders API route</deliverable>
  </output_format>
</enriched_prompt>

Failure Modes to Avoid

• Don't ask all 5 questions upfront. It feels like a bureaucratic form. Ask the most critical one first.
• Don't block on partial information. After 3 rounds, fill the gaps with reasonable assumptions and label them [assumed].
• Don't paraphrase back the entire original prompt. State the enriched intent in your own words.
• Don't clarify obvious things. If the user says "fix the TypeScript error in src/auth.ts:42", proceed — that's already specific enough.