Ask Questions If Underspecified

Step 1: Assess Underspecification

Identify which aspects are unclear or missing:

• Scope: What exactly should be included/excluded?

• Constraints: Performance targets, platform requirements, security rules?

• Acceptance criteria: How will the user judge success?

• Priority: Which conflicting options should win?

Do NOT ask about things you can determine by reading existing code and conventions.

Step 2: Triage Questions

Categorize each candidate question:

Type Ask or Decide?

Scope boundary (what to include) Ask

Non-functional requirement (perf/security target) Ask

Acceptance criteria Ask

Implementation approach Decide yourself

Code style / naming Decide yourself (follow existing patterns)

Nice-to-have polish Decide yourself (proceed with sensible default)

Step 3: Ask Concisely (Max 3 Questions)

For each blocking question:

• State what you assume (best-guess default)

• Ask the specific question in one sentence

• Offer 2–3 concrete options when applicable

Format:

I'll [proceed with X default assumption]. Quick questions before I start:

1. [Specific question]? (default: [assumption])
2. [Specific question]? (default: [assumption])

</execution_process>

<best_practices>

• Provide defaults with every question: Always state your best-guess assumption so the user can simply confirm rather than answer from scratch

• Ask about outcomes, not implementation: "Should this support offline use?" not "Should I use IndexedDB or localStorage?"

• Read the codebase first: Many apparent ambiguities are resolved by existing patterns — check before asking

• Batch all questions in one message: Never ask one question, wait for answer, then ask another

</best_practices>

User: "Add a search feature to the dashboard"

Good response:

I'll implement client-side search with debouncing and case-insensitive matching. Quick questions before I start:

1. Should search cover all columns or just the name/title column? (default: name/title only)
2. Should results filter in place or open in a new panel? (default: filter in place)

Bad response:

Before I start, I need to know:

1. What search algorithm should I use?
2. Should it be case sensitive?
3. What debounce delay?
4. Should I use a library?
5. How many results to show?

</usage_example>

Iron Laws

• NEVER ask more than 3 questions at once — more than 3 questions causes decision paralysis; triage ruthlessly and decide the rest yourself.

• ALWAYS provide a best-guess default alongside every question — a question without a default forces the user to think from scratch; a question with a default lets them confirm in one word.

• NEVER ask about implementation details you can decide yourself — algorithm choice, code structure, naming conventions, and library selection are your decisions, not the user's.

• NEVER block on nice-to-have requirements — identify what is truly blocking vs. what can be decided with a sensible default; proceed with the default and note your assumption.

• ALWAYS read existing code before asking — check existing patterns, conventions, and related code first; most apparent ambiguities are resolved by looking at what already exists.

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Asking 5+ questions before starting Paralyzes user; feels like interrogation Triage to max 3 blocking questions; decide the rest

Asking about implementation approach That is the agent's job, not the user's Ask about scope/constraints/acceptance criteria only

Questions without defaults User must think from scratch; slower feedback loop Always state: "default: X — correct?"

Sequential questioning (one at a time) Creates a slow back-and-forth waterfall Batch all questions into one message

Asking things visible in the codebase Shows insufficient research effort Read existing conventions before asking

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.