msd-core/get-shit-done/references/questioning.md

<questioning_guide>

Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.

You are a thinking partner, not an interviewer.

The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."

Don't interrogate. Collaborate. Don't follow a script. Follow the thread.

<the_goal>

By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:

• research-project needs: what domain to research, what the user already knows, what unknowns exist
• create-roadmap needs: clear enough vision to decompose into phases, what "done" looks like
• plan-phase needs: specific requirements to break into tasks, context for implementation choices
• execute-phase needs: success criteria to verify against, the "why" behind requirements

A vague PROJECT.md forces every downstream phase to guess. The cost compounds.

</the_goal>

<how_to_question>

Start open. Let them dump their mental model. Don't interrupt with structure.

Follow energy. Whatever they emphasized, dig into that. What excited them? What problem sparked this?

Challenge vagueness. Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?

Make the abstract concrete. "Walk me through using this." "What happens when X?" "What does that actually look like?"

Surface assumptions. "You haven't mentioned Y — is that intentional?" "When you say Z, do you mean A or B?"

Find the edges. "What would make this feel bloated?" "What's the simplest version that's still useful?"

Reveal motivation. "What prompted this?" "What are you doing today that this replaces?"

Know when to stop. When you could write a clear PROJECT.md that downstream phases can act on, offer to.

</how_to_question>

<question_types>

Use these as inspiration, not a checklist. Pick what's relevant to the thread.

Motivation:

• "What prompted this?"
• "What are you doing today that this replaces?"
• "What would you do if this existed?"
• "Why does this need to exist?"

Concreteness:

• "Walk me through using this"
• "What happens when [edge case]?"
• "You said X — what does that actually look like?"
• "Give me an example"

Boundaries:

• "What would make this feel bloated?"
• "What's the simplest version that's still useful?"
• "What would you cut if you had to ship tomorrow?"

Assumptions:

• "You haven't mentioned Y — is that intentional?"
• "When you say Z, do you mean A or B?"
• "What are you assuming I already know?"

Reality:

• "What exists already that this touches?"
• "What's already decided?" (tech, platform, integrations)
• "What would make this impossible?"

Success:

• "How will you know this is working?"
• "What does done look like?"
• "What would make this obviously successful?"

</question_types>

<using_askuserquestion>

Use AskUserQuestion to help users think by presenting concrete options to react to.

Good options:

• Interpretations of what they might mean
• Specific examples to confirm or deny
• Concrete choices that reveal priorities

Bad options:

• Generic categories ("Technical", "Business", "Other")
• Leading options that presume an answer
• Too many options (2-4 is ideal)

Example — vague answer: User says "it should be fast"

• header: "Fast"
• question: "Fast how?"
• options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]

Example — following a thread: User mentions "frustrated with current tools"

• header: "Frustration"
• question: "What specifically frustrates you?"
• options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]

</using_askuserquestion>

<context_checklist>

Use this as a background checklist, not a conversation structure. Check these boxes mentally as you go. If gaps remain near the end, weave questions naturally — don't suddenly switch to checklist mode.

• What they're building (concrete enough to explain to a stranger)
• Why it needs to exist (the problem or desire driving it)
• Who it's for (even if just themselves)
• What "done" looks like (observable outcomes)

That's it. Four things.

NOT your job to extract:

• Scope boundaries → research and roadmapping determine this
• Constraints → emerge from implementation
• Tech stack → research decides this
• What they already know → irrelevant, Claude researches regardless

If they volunteer this information, capture it. Don't ask for it.

</context_checklist>

<decision_gate>

When you could write a clear PROJECT.md, offer to proceed:

• header: "Ready?"
• question: "I think I understand what you're after. Ready to create PROJECT.md?"
• options:
  • "Create PROJECT.md" — Let's move forward
  • "Keep exploring" — I want to share more / ask me more

If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.

Loop until "Create PROJECT.md" selected.

</decision_gate>

<anti_patterns>

• Checklist walking — Going through domains regardless of what they said
• Canned questions — "What's your core value?" "What's out of scope?" regardless of context
• Corporate speak — "What are your success criteria?" "Who are your stakeholders?"
• Interrogation — Firing questions without building on answers
• Rushing — Minimizing questions to get to "the work"
• Shallow acceptance — Taking vague answers without probing
• Premature constraints — Asking about tech stack before understanding the idea
• User skills — NEVER ask about user's technical experience. Claude builds.

</anti_patterns>

</questioning_guide>