| name | intent-interview |
| description | Clarifies an ambiguous request before planning or coding by stating a hypothesis, asking one focused question at a time with Pi's guess, and confirming a concise intent block. Use when the user's ask lacks who, why, success criteria, constraints, or scope; when they say 'interview me', 'grill me', or 'are we sure'; or when you would otherwise silently assume requirements. |
Intent Interview
Overview
Use this skill to discover what the user actually wants before committing to a spec, plan, or code. The goal is not to collect every possible requirement; it is to close the gap between the user's first wording and the outcome they would be happy with.
Good intent interviewing is lightweight: state your current read, ask one sharp question, attach your best guess, and let the user correct you. Stop as soon as the intent is clear enough to act on.
When to Use
Use this skill when:
- The request is missing any of: who it is for, why it matters, what success looks like, the main constraint, or what is out of scope.
- The request is conventional or vague: "build a dashboard", "make this faster", "improve the UX", "add memory", "clean this up".
- Two reasonable values are in tension: speed vs. quality, simplicity vs. flexibility, local fix vs. broad refactor.
- You catch yourself silently inventing requirements.
- The user explicitly asks: "interview me", "grill me", "ask me questions first", "are we sure?", or "stress-test what I want".
Do not use this skill for:
- Clear mechanical edits, typo fixes, renames, or formatting.
- Pure information requests: "what does this code do?", "compare these options", "summarize this file".
- Small bug fixes where reproduction and acceptance criteria are already clear.
- Cases where the user explicitly asks for the quick obvious version and accepts the risk.
- Non-interactive or scheduled work where the user cannot answer; in that case, state the blocker instead of guessing.
The Process
1. Start with a hypothesis and confidence
Before asking anything, state your current best read in one sentence and give an honest confidence number.
HYPOTHESIS: You want <outcome>, because <reason inferred from the request>.
CONFIDENCE: ~40% — missing: <what is still unresolved>.
Rules:
- Keep the hypothesis to one sentence.
- If confidence is below ~70%, include the reason: what is missing or uncertain.
- Do not inflate the number. If you cannot predict how the user will answer the next few questions, confidence is not high.
2. Ask one question at a time, with your guess attached
Format each turn like this:
Q: <one focused question>
GUESS: <your best guess and why you think it might be true>
Ask only one question per message. Do not send a questionnaire. The user's answer to the first question should influence the second question.
Why attach a guess:
- Users correct a wrong guess faster than they generate an answer from scratch.
- It exposes your assumptions.
- It prevents vague survey-style questioning.
3. Watch for "want" vs. "should want"
Be alert when the user answers with convention or sophistication signaling rather than a concrete desired outcome:
- "best practice"
- "scalable"
- "clean architecture"
- "the standard way"
- "modern"
- "whatever you think"
When this happens, ask:
If you didn't have to justify this to anyone, what would you actually want?
Use this sparingly, but do not skip it when the user's answer sounds like what someone thinks they should want rather than what would solve their problem.
4. Update confidence and stop when useful clarity is reached
After each answer, update your read briefly:
Updated read: <new understanding>.
Confidence: ~75% — still missing: <remaining uncertainty>.
Stop interviewing when you can confidently fill in the final intent block below. A practical stop test:
Can I predict the user's reaction to the next three questions I would ask?
If yes, stop and confirm. If no, ask the next focused question.
If confidence does not improve after several rounds, stop and say so:
I've asked a few questions and my confidence is not rising. Something foundational is still unclear. Want to step back and reframe the goal?
5. Restate and get explicit confirmation
When the intent is clear, restate it in a compact block:
## Confirmed Intent
- Outcome: <what we are trying to achieve>
- User: <who benefits or uses it>
- Why now: <what prompted this / why it matters>
- Success: <how we know it worked>
- Constraint: <main limit, trade-off, or priority>
- Out of scope: <what we are explicitly not doing>
Proceed? yes / refine
Do not treat "whatever you think" as confirmation. If the user delegates, turn it into a concrete choice:
I can take this in either direction:
A) <simpler / narrower option>
B) <broader / more flexible option>
Which should I optimize for?
6. Handoff after confirmation
Only after the user confirms the intent should you proceed to downstream work:
- For a new feature or substantial change, move to a spec or plan.
- For implementation, start normal codebase exploration and task tracking.
- For research, use the appropriate research workflow.
- For a small clarified change, state the plan briefly and execute.
Do not create files, edit code, or build a long task list during the interview unless the user explicitly asks.
Pi-Specific Guidance
- Use normal chat. No custom UI is required.
- Keep messages short; the point is alignment, not ceremony.
- Do not use
todo_update during the interview unless implementation starts afterward.
- If code context is needed to ask a better question, inspect only the minimal relevant context, then return to the interview.
- If the user asks to save the confirmed intent, offer a path such as
docs/intent/<topic>.md and write it only after confirmation.
Common Rationalizations
| Rationalization | Reality |
|---|
| "The ask is clear enough." | If you cannot state Outcome/User/Success/Constraint/Out of scope, it is not clear enough for non-trivial work. |
| "Questions slow us down." | One good question is cheaper than building the wrong thing. |
| "I'll figure it out while coding." | Discovery during implementation becomes rework. Clarify before there is code to defend. |
| "The user said whatever I think." | That is delegation, not confirmation. Offer concrete choices. |
| "I'll ask all questions at once." | Batched questions produce shallow answers and prevent adaptation. Ask one at a time. |
| "Best practice is enough." | Best practice is a means, not the user's desired outcome. Ask what they actually want. |
Red Flags
- Asking three or more questions in one message.
- Asking a question without attaching your guess.
- Starting a spec, plan, or implementation before the confirmed intent block.
- Accepting "sounds good" or "whatever you think" without checking whether anything should be refined.
- Skipping the "Out of scope" line.
- Confidence below ~70% with no explanation of what is missing.
- Several rounds of questions with no visible increase in confidence.
Verification
Before leaving the skill, confirm:
