Enriches vague, low-detail prompts into structured, agent-optimized XML before execution. INVOKE IMMEDIATELY — before any tool use or file reads — when you detect any of these signals: prompt under 10 words with no file path or error message; vague action verbs with no object ("fix the bug", "make it better", "clean this up", "refactor this", "optimize performance", "improve the UI", "add authentication", "add payments", "add notifications", "build the feature"); CLARIFIER_ADVISORY in your context window; user says "clarify", "help me describe this", "enrich this prompt", "structure my request". Also triggers on: "make this work", "it's broken", "it looks bad", "add X" with no further detail, "implement Y" with no constraints. Do NOT trigger on: prompts ending with ?, prompts containing error messages or stack traces, prompts with specific file paths, prompts already containing acceptance criteria or success metrics.
Instrucciones de origen · Vista previa de solo lectura
name
prompt-clarifier
description
Enriches vague, low-detail prompts into structured, agent-optimized XML before execution. INVOKE IMMEDIATELY — before any tool use or file reads — when you detect any of these signals: prompt under 10 words with no file path or error message; vague action verbs with no object ("fix the bug", "make it better", "clean this up", "refactor this", "optimize performance", "improve the UI", "add authentication", "add payments", "add notifications", "build the feature"); CLARIFIER_ADVISORY in your context window; user says "clarify", "help me describe this", "enrich this prompt", "structure my request". Also triggers on: "make this work", "it's broken", "it looks bad", "add X" with no further detail, "implement Y" with no constraints. Do NOT trigger on: prompts ending with ?, prompts containing error messages or stack traces, prompts with specific file paths, prompts already containing acceptance criteria or success metrics.
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:
Dimension
The question it answers
Priority
Intent
What does "done" look like?
Always ask first
Scope
What is explicitly out of scope?
Ask for "add X" / "build X" prompts
Constraints
What must not change or break?
Ask for risky changes (auth, payments, data)
Success Criteria
How will you verify it worked?
Ask if not implied by Intent
Context
Which files / components are the entry point?
Ask if no file paths mentioned
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.
