Interactive Questions with AskUserQuestion Tool

Instructions

When to ask

Always ask when:

• Requirements unclear
• Missing critical information
• Multiple interpretations possible
• Trade-offs need decision
• Configuration or setup choices needed
• User needs to select from multiple options

Never assume - Always ask!

Question Framework Using AskUserQuestion

The AskUserQuestion tool provides a structured way to ask questions with clear options.

Tool Structure

AskUserQuestion({
  questions: [
    {
      question: "Clear question text?",
      header: "Short label (max 12 chars)",
      multiSelect: false,  // true if multiple selections allowed
      options: [
        {
          label: "Option 1",
          description: "What this option means and its implications"
        },
        {
          label: "Option 2",
          description: "Another choice with trade-offs"
        }
      ]
    }
  ]
})

Best Practices

1. Keep headers short (max 12 characters) - e.g., "Auth method", "Test type"
2. Clear questions - End with "?" and be specific
3. Provide 2-4 options - Not too few, not too many
4. Descriptive labels - Concise (1-5 words)
5. Explain trade-offs - Each option's pros/cons
6. Use multiSelect - When choices aren't mutually exclusive
7. "Other" is automatic - Don't add it, users can always provide custom input

Question Framework Steps

1. Identify the gap - What information is missing?
2. Formulate specific question - Make it clear and unambiguous
3. Provide context - Why does this matter?
4. Offer options - Use AskUserQuestion with 2-4 choices
5. Explain implications - What each option means

Example

Request: "Add validation to {{ENTITIES}}"

❌ Don't Assume

"Implementing {{field1}} and {{field2}} validation with min/max rules..."

✅ Use AskUserQuestion

AskUserQuestion({
  questions: [
    {
      question: "Which fields need validation?",
      header: "Fields",
      multiSelect: true,  // User can select multiple fields
      options: [
        {
          label: "{{field1}}",
          description: "Primary identifier field"
        },
        {
          label: "{{field2}}",
          description: "Numeric value field"
        },
        {
          label: "{{field3}}",
          description: "Status field"
        }
      ]
    },
    {
      question: "What validation rules for {{field1}}?",
      header: "{{field1}} Rule",
      multiSelect: false,
      options: [
        {
          label: "Range check",
          description: "Validate min/max values (strict bounds)"
        },
        {
          label: "Format check",
          description: "Validate format/pattern only"
        },
        {
          label: "Both",
          description: "Range and format validation"
        }
      ]
    },
    {
      question: "How should validation failures be handled?",
      header: "Error Handle",
      multiSelect: false,
      options: [
        {
          label: "Exception",
          description: "Throw exception immediately (fail fast)"
        },
        {
          label: "Error object",
          description: "Return error object (allow recovery)"
        },
        {
          label: "Collect all",
          description: "Validate all fields, return all errors"
        }
      ]
    }
  ]
})

Common Scenarios

Scenario 1: Feature Scope Ambiguity

Request: "Add authentication"

Using AskUserQuestion:

AskUserQuestion({
  questions: [
    {
      question: "Which authentication method should be implemented?",
      header: "Auth Method",
      multiSelect: false,
      options: [
        {
          label: "JWT tokens",
          description: "Stateless, scalable, good for APIs (recommended for microservices)"
        },
        {
          label: "Session-based",
          description: "Traditional, stateful, server-side sessions (simpler for monoliths)"
        },
        {
          label: "OAuth2",
          description: "Third-party auth (Google, GitHub, etc.), more complex setup"
        },
        {
          label: "API keys",
          description: "Simple, for service-to-service auth only"
        }
      ]
    },
    {
      question: "What should be protected by authentication?",
      header: "Protection",
      multiSelect: true,  // Can protect multiple areas
      options: [
        {
          label: "All endpoints",
          description: "Everything requires auth (most secure, may impact public APIs)"
        },
        {
          label: "User resources",
          description: "Only user-specific data (balance security and accessibility)"
        },
        {
          label: "Admin only",
          description: "Administrative routes only (least restrictive)"
        }
      ]
    },
    {
      question: "Where should credentials be stored?",
      header: "Storage",
      multiSelect: false,
      options: [
        {
          label: "Database",
          description: "Full control, your infrastructure (requires secure hashing)"
        },
        {
          label: "External (Auth0)",
          description: "Managed service, easier but external dependency"
        },
        {
          label: "In-memory cache",
          description: "Fast but lost on restart (dev/testing only)"
        }
      ]
    }
  ]
})

Scenario 2: Technical Implementation Choices

Request: "Improve performance"

Using AskUserQuestion:

AskUserQuestion({
  questions: [
    {
      question: "What is the primary performance target?",
      header: "Target",
      multiSelect: false,
      options: [
        {
          label: "Response time",
          description: "Reduce latency, faster user experience (< 200ms target)"
        },
        {
          label: "Throughput",
          description: "Handle more concurrent requests (> 1000 req/s)"
        },
        {
          label: "Memory usage",
          description: "Reduce RAM consumption (< 512MB target)"
        },
        {
          label: "All of above",
          description: "Comprehensive optimization (most effort required)"
        }
      ]
    },
    {
      question: "Which operations are currently slow?",
      header: "Bottleneck",
      multiSelect: true,
      options: [
        {
          label: "Database queries",
          description: "Slow SQL, N+1 problems, missing indexes"
        },
        {
          label: "API calls",
          description: "External service latency, no caching"
        },
        {
          label: "File processing",
          description: "Large file I/O, inefficient parsing"
        }
      ]
    }
  ]
})

Scenario 3: Error Handling Strategy

Request: "Handle edge cases"

Using AskUserQuestion:

AskUserQuestion({
  questions: [
    {
      question: "What edge cases need handling?",
      header: "Edge Cases",
      multiSelect: true,
      options: [
        {
          label: "Empty input",
          description: "User provides no data or blank fields"
        },
        {
          label: "Null values",
          description: "Missing or undefined data in system"
        },
        {
          label: "Concurrent access",
          description: "Multiple users modifying same resource"
        },
        {
          label: "Network failures",
          description: "External service unavailable or timeout"
        }
      ]
    },
    {
      question: "How should errors be handled?",
      header: "Strategy",
      multiSelect: false,
      options: [
        {
          label: "Fail fast",
          description: "Throw exception immediately (explicit errors, debugging easier)"
        },
        {
          label: "Graceful degradation",
          description: "Use defaults, continue operation (better UX, may hide issues)"
        },
        {
          label: "Retry with backoff",
          description: "Auto-retry with delays (good for transient failures)"
        },
        {
          label: "Log and continue",
          description: "Record error, proceed (background jobs, non-critical)"
        }
      ]
    }
  ]
})

Scenario 4: Data Migration/Schema Changes

Request: "Update database schema"

Using AskUserQuestion:

AskUserQuestion({
  questions: [
    {
      question: "How should existing data be handled?",
      header: "Migration",
      multiSelect: false,
      options: [
        {
          label: "Auto-migrate",
          description: "Migrate data automatically on deployment (safe, recommended)"
        },
        {
          label: "Manual migration",
          description: "Provide script, admin runs it (more control, manual step)"
        },
        {
          label: "Drop & recreate",
          description: "Delete old data (dev/test only, NOT for production)"
        }
      ]
    },
    {
      question: "What are backwards compatibility requirements?",
      header: "Compatibility",
      multiSelect: false,
      options: [
        {
          label: "Fully compatible",
          description: "Old code must work (safest, may limit changes)"
        },
        {
          label: "Grace period",
          description: "Deprecation warnings, 1-2 releases to migrate (balanced)"
        },
        {
          label: "Breaking change OK",
          description: "Can break old code (fastest, requires coordination)"
        }
      ]
    },
    {
      question: "When should the migration be applied?",
      header: "Timing",
      multiSelect: false,
      options: [
        {
          label: "Immediate",
          description: "Next deployment (for small changes, low traffic)"
        },
        {
          label: "Maintenance window",
          description: "Scheduled downtime (for large migrations, high impact)"
        },
        {
          label: "Gradual rollout",
          description: "Phased migration (for critical systems, zero downtime needed)"
        }
      ]
    }
  ]
})

Advanced Usage

Multiple Questions in Sequence

Ask up to 4 questions at once for complex scenarios:

AskUserQuestion({
  questions: [
    {
      question: "Question 1?",
      header: "Header 1",
      multiSelect: false,
      options: [...]
    },
    {
      question: "Question 2?",
      header: "Header 2",
      multiSelect: false,
      options: [...]
    },
    {
      question: "Question 3?",
      header: "Header 3",
      multiSelect: true,  // Multiple selections allowed
      options: [...]
    },
    {
      question: "Question 4?",
      header: "Header 4",
      multiSelect: false,
      options: [...]
    }
  ]
})

Conditional Questions

Based on previous answers, ask follow-up questions:

// First question
AskUserQuestion({
  questions: [{
    question: "Do you want to enable caching?",
    header: "Caching",
    multiSelect: false,
    options: [
      { label: "Yes", description: "Enable caching for better performance" },
      { label: "No", description: "No caching needed" }
    ]
  }]
})

// If answer is "Yes", ask follow-up:
if (answer === "Yes") {
  AskUserQuestion({
    questions: [{
      question: "Which caching strategy?",
      header: "Strategy",
      multiSelect: false,
      options: [
        { label: "Redis", description: "Distributed cache, scalable" },
        { label: "In-memory", description: "Fast but per-instance" },
        { label: "CDN", description: "Edge caching for static assets" }
      ]
    }]
  })
}

Integration with Other Skills

Use with plugin-setup

The plugin-setup skill uses this skill extensively for configuration:

// plugin-setup calls this skill
Skill("interactive-questions")

// Then uses AskUserQuestion for all setup questions
AskUserQuestion({
  questions: [
    { question: "Project type?", ... },
    { question: "Issue tracker?", ... },
    ...
  ]
})

Use with project-planner

When requirements are unclear during planning:

// In project-planner agent
if (requirementsUnclear) {
  Skill("interactive-questions")
  
  AskUserQuestion({
    questions: [{
      question: "Which approach do you prefer?",
      header: "Approach",
      multiSelect: false,
      options: [
        { label: "Option A", description: "Pros and cons..." },
        { label: "Option B", description: "Trade-offs..." }
      ]
    }]
  })
}

Tips for Effective Questions

1. Be Specific: Vague questions get vague answers

   • ❌ "How to do it?"
   • ✅ "Which validation strategy: client-side, server-side, or both?"

2. Provide Context: Explain why it matters

   • Include trade-offs in descriptions
   • Mention performance, security, or maintenance implications

3. Limit Options: 2-4 options ideal

   • Too few: Not helpful
   • Too many: Overwhelming
   • User can always select "Other" for custom input

4. Use Clear Labels: 1-5 words max

   • ❌ "Use the traditional session-based authentication mechanism"
   • ✅ "Session-based"

5. Actionable Descriptions: Explain what each option does

   • Include estimated effort if relevant
   • Mention if it's the recommended option

6. Group Related Questions: Ask them together

   • Use multiSelect when answers aren't exclusive
   • Use single select for either/or decisions

---

For detailed patterns, see reference.md For more examples, see examples.md