Interview Me

Conduct a systematic interview to gather complete information about the topic at hand. Use a question tool (e.g., Claude Code's AskUserQuestion) to ask one structured question at a time, providing full context and educated guesses so the user can answer with a single click or tap.

CRITICAL: Never append interview results as a lazy dump at the end of documents. ALWAYS integrate findings into the appropriate existing sections, refactoring and reorganizing as needed.

Prerequisites

The interview's findings must live in an artifact or file — not in the chat. Chat content is hard to track and impossible to integrate cleanly after the fact; artifacts and files are the source of truth that the agent updates incrementally as each answer comes in. If the user hasn't named a target file, confirm one before asking the first question (see Step 2 of The Flow).

Use a question tool that exposes single-select options alongside a free-form text input when one is available (e.g., Claude Code's AskUserQuestion). If none is available, present the options as a short numbered or coded list and let the user reply with the number, code, or a free-form answer. For voice mode, see Voice Mode Adaptation.

Core Principles

• Provide full context — Present all relevant information with each question (assume the user is unable to look at related info).
• Analyze and recommend — Do your own analysis and provide recommendations based on gathered information.
• Minimize user effort — Frame questions to require minimal cognitive and input effort.
• Use educated guesses — Make intelligent assumptions and ask for confirmation.
• Prefer structured responses — Use yes/no, multiple choice, or short answers when possible.
• Structure responses for quick scanning — Use clear headers, bullets, and emphasis.
• Execute immediately — After each user answer, execute the resulting action immediately. Do not batch actions until the end. Make the change, then ask the next question.
• INTEGRATE, DON'T APPEND — NEVER dump interview results at the bottom of the artifact. ALWAYS find the right place to merge them in. Refactor sections. Update existing content. Make it flow naturally. This is NON-NEGOTIABLE.

The Flow

1. Confirm the interview topic. From arguments, context, or by asking the user.

2. Confirm where to record responses. Suggest a location based on context — an existing doc, a new file, or wherever fits the project.

3. Plan the questions. Create an organized list, broad to specific, and minimize the total number.

4. Ask the user one question at a time using the question tool. Reprint the relevant context (background, current state, your educated guess) in the chat message before invoking the question tool, so the user can read without switching context. The question prompt itself stays short — a label, not the whole context block. Use a single-select question shaped by the rules in Question options below.

   Claude Code-only workaround: end every chat reprint with a blank line, then a horizontal rule (---), then another blank line, before invoking AskUserQuestion. This bug is specific to Claude Code: its AskUserQuestion UI renders as a card that overlays the chat and clips the last line of prior content. Other surfaces (Claude.ai web, Claude iOS, voice mode, and anything that doesn't use AskUserQuestion) do not have this problem — they render the question below the reprint without clipping. The trailing --- acts as a sacrificial line that absorbs the clip and visually anchors the end of the chunk in scrollback. Measured empirically in current Claude Code: the card clips exactly 1 line, and a single rule is sufficient. The blank line before --- is required — without it, CommonMark parses the rule as a setext H2 underline of the prose above, not a horizontal rule. Place the rule outside any code fences. The rule is harmless on non-Claude-Code surfaces, so apply it unconditionally rather than branching on surface. Drop this once Claude Code's question UI no longer clips.

5. Apply the answer immediately, then move on. After each answer, execute the resulting action — update the doc, edit the code, record the decision — before asking the next question. Do not batch.

6. INTEGRATE documentation properly. CRITICAL REQUIREMENT:

   • NEVER append interview results at the end of a document.
   • ALWAYS find the correct existing section to update.
   • Refactor and reorganize sections as needed.
   • Update existing content to incorporate new decisions.
   • Ensure information flows naturally within the document structure.
   • If no appropriate section exists, create one in the logical place.

7. Provide analysis at the end. Once questions are exhausted:

   • Summarize key findings.
   • Identify patterns and insights.
   • Make specific recommendations.
   • Structure output for easy scanning.
   • MANDATORY: Integrate ALL conclusions into appropriate sections of the target artifact. NEVER append the conclusions to the end of the file as a "Findings" or "Interview results" block. Find the right headers, update existing paragraphs, and maintain document flow.

8. Follow user cues. Move on when they're ready; stop when they say so.

Question options

Each interview question should offer up to 4 options. Default to single-select; use multi-select only when answers can compound (e.g., "Which of these apply?"). The user should also be able to type a free-form answer alongside the options — see the free-form feedback rule below for how to confirm the surface exposes one.

Example

Based on your project structure, it looks like you're using vanilla
JavaScript with Web Components. Is this correct?

[Question tool, single-select]

- Yes
- No, it's TypeScript
- No, it's a framework (React/Vue/Svelte)
- Not sure — show me how to check
- [Type your answer…] (free-form text input, not a button)

Rules

• Default to single-select. Saves the user a tap on mobile. Use multi-select only when answers can compound. The user can type a free-form response in the chat input if none of the options fit.
• Cap the total at 4 options. Some question tools (e.g., Claude Code's AskUserQuestion) reject more than 4. Pick the 4 most likely answers based on your educated guess; the user can still type anything else.
• Options must be specific to the question, not generic. For yes/no, use Yes / No (and an optional "Not sure" or a specific alternative). For multiple choice, list concrete answers, not vague labels like "Other" or "Something else". Generic options waste a slot.
• Lead with your best guess when there is one. If your context already points to a likely answer, make it the first option (often phrased as a confirmation of your guess) so the user can approve it with one click or tap.
• The user must always be able to give free-form feedback. Rely on the question surface's built-in free-text affordance — don't add your own "Open feedback" or "Other" bullet to the option list. An agent-added "Other" option submits the literal string "Other" instead of opening a text input; the surface's built-in input opens a real text field. Confirm the surface's behavior up front; don't test it with the user. Compatibility notes: Claude.ai (iOS verified) renders a text input below every question; Claude Code's AskUserQuestion provides a built-in "Other" free-text affordance — that's the tool-provided input, distinct from an agent-added bullet labeled "Other".
• Ask one question at a time. Don't batch multiple questions into a single turn. The interview's value comes from focus and immediate follow-through after each answer.

Voice Mode Adaptation

In voice mode there's no question tool, no buttons, no text input — just the agent speaking and the user speaking. The same interview pattern still works, with these adaptations:

• State the context aloud first. Read the relevant background, current state, and your educated guess before asking the question, so the user has what they need to answer without referring to a screen.
• Read the question and offer options as a phone menu. "Are you using vanilla JavaScript with Web Components? Say 'yes' to confirm, 'no' if it's TypeScript, or describe what you're using in your own words." Keep to 2–3 spoken options max; longer lists are hard to track in audio.
• Always invite a free-form spoken answer. End the menu with an open prompt ("…or just tell me") so the user isn't forced into the listed options.
• Apply the answer and confirm aloud before moving on. Say what you're changing ("Got it — I'll add that to the architecture section now") so the user has the same execute-immediately feedback loop they'd see in text.