Enterprise Interactive Survey Orchestrator

Skill Metadata

Field	Value
Skill Name	moai-core-ask-user-questions
Version	4.0.0 Enterprise (2025-11-18)
Core Tool	AskUserQuestion (Claude Code built-in)
Auto-load	When Alfred detects ambiguity in requests
Tier	Alfred (Workflow Orchestration)
Allowed tools	AskUserQuestion
Lines of Content	850+, with 10+ production examples
Progressive Disclosure	3-level (quick-reference, patterns, advanced)

---

🚀 What It Does (Enterprise Context)

Purpose: Empower Alfred sub-agents to actively conduct enterprise-grade surveys for requirement clarification, architectural decisions, and complex decision automation.

Leverages Claude Code's native AskUserQuestion tool to collect explicit, structured user input that transforms vague requests into precise specifications with guaranteed UX quality across all models.

Enterprise Capabilities:

• ✅ Single-select & multi-select option types (independent or dependent)
• ✅ 1-4 questions per survey (cognitive load optimization)
• ✅ 2-4 options per question with trade-off analysis
• ✅ Automatic "Other" option for custom input validation
• ✅ Conditional branching based on user answers
• ✅ Error recovery and retry logic
• ✅ Integration across all Alfred commands (Plan/Run/Sync)
• ✅ Multi-language support (user's configured language)
• ✅ Accessibility-first TUI design
• ✅ Reduces ambiguity → single interaction vs 3-5 iterations

---

🎯 When to Use (Decision Framework)

✅ MANDATORY ASK when user intent is ambiguous:

1. Vague noun phrases: "Add dashboard", "Refactor auth", "Improve performance"

   • Missing concrete specification or scope

2. Missing scope definition: No specification of WHERE, WHO, WHAT, HOW, WHEN

   • Could affect 5+ files or multiple modules

3. Multiple valid paths: ≥2 reasonable implementation approaches

   • Different trade-offs (speed vs quality, simple vs comprehensive)

4. Trade-off decisions: Performance vs reliability, cost vs features

   • No single objectively best answer

5. Risky operations: Destructive actions (delete, migrate, reset)

   • Explicit informed consent required

6. Architectural decisions: Technology selection, API design, database choice

   • Long-term impact requires clarification

❌ DON'T ask when:

• User explicitly specified exact requirements
• Decision is automatic (no choices, pure routing)
• Single obvious path exists (no alternatives)
• Quick yes/no confirmation only (keep it brief)
• Information already provided in conversation

---

🎨 Design Principles (Enterprise Standards)

Core Principle: Certainty Over Guessing

Golden Rule: When in doubt, ask the user instead of assuming.

Why:

• ✅ User sees exactly what you'll do → no surprises
• ✅ Single interaction vs 3-5 rounds of back-and-forth
• ✅ Fast → execute with certainty
• ✅ Reduces "vibe coding" frustration
• ✅ Builds trust through transparency

Pattern:

Ambiguous request detected
         ↓
Call AskUserQuestion({questions: [...]})
         ↓
User selects from clear options
         ↓
Proceed with confirmed specifications

---

🏗️ Architecture: 3-Level Progressive Disclosure

Level 1: Quick Start (Minimal Invocation)

Single-Select Pattern:

const answer = await AskUserQuestion({
  questions: [
    {
      question: "How should we implement this?",
      header: "Approach",          // max 12 chars
      multiSelect: false,
      options: [
        {
          label: "Option 1",       // 1-5 words
          description: "What it does and why you'd pick it."
        },
        {
          label: "Option 2",
          description: "Alternative with different trade-offs."
        }
      ]
    }
  ]
});

// Returns: { "Approach": "Option 1" }

Multi-Select Pattern (independent features):

const answer = await AskUserQuestion({
  questions: [
    {
      question: "Which features should we enable?",
      header: "Features",
      multiSelect: true,
      options: [
        { label: "Feature A", description: "..." },
        { label: "Feature B", description: "..." },
        { label: "Feature C", description: "..." }
      ]
    }
  ]
});

// Returns: { "Features": ["Feature A", "Feature C"] }

Level 2: Enterprise Patterns

Batch Questions (related decisions):

const answer = await AskUserQuestion({
  questions: [
    {
      question: "Which database technology?",
      header: "Database",
      options: [
        { label: "PostgreSQL", description: "Relational, ACID, mature" },
        { label: "MongoDB", description: "Document, flexible schema" }
      ]
    },
    {
      question: "Cache strategy?",
      header: "Caching",
      options: [
        { label: "Redis", description: "In-memory, fast" },
        { label: "Memcached", description: "Distributed cache" }
      ]
    }
  ]
});

Conditional Flow (dependent decisions):

let questions = [
  {
    question: "What type of deployment?",
    header: "Deployment Type",
    options: [
      { label: "Docker", description: "Containerized" },
      { label: "Kubernetes", description: "Orchestrated" },
      { label: "Serverless", description: "Functions-as-a-Service" }
    ]
  }
];

const initialAnswer = await AskUserQuestion({ questions });

// Follow-up based on initial choice
if (initialAnswer["Deployment Type"] === "Kubernetes") {
  const kubeAnswer = await AskUserQuestion({
    questions: [
      {
        question: "Which cluster provider?",
        header: "K8s Provider",
        options: [
          { label: "AWS EKS", description: "Amazon Elastic Kubernetes" },
          { label: "GCP GKE", description: "Google Kubernetes Engine" },
          { label: "Self-Managed", description: "On-premises cluster" }
        ]
      }
    ]
  });
}

Level 3: Advanced (Error Handling & Validation)

Custom Input Validation ("Other" option):

const answer = await AskUserQuestion({
  questions: [
    {
      question: "Which framework?",
      header: "Framework",
      options: [
        { label: "React", description: "UI library" },
        { label: "Vue", description: "Progressive framework" },
        { label: "Other", description: "Custom framework or library" }
      ]
    }
  ]
});

// Validate custom input
if (answer["Framework"] === "Other" || 
    !VALID_FRAMEWORKS.includes(answer["Framework"])) {
  const customAnswer = validateCustomInput(answer["Framework"]);
  if (!customAnswer) {
    // Re-ask with guidance
    return retryWithGuidance();
  }
}

Error Recovery:

try {
  const answer = await AskUserQuestion({...});
} catch (error) {
  if (error.type === "UserCancelled") {
    // User pressed ESC - use default or abort
    return fallbackToDefault();
  } else if (error.type === "InvalidInput") {
    // Validate and retry
    return retryWithValidation();
  }
}

Risky Operation Confirmation:

const answer = await AskUserQuestion({
  questions: [
    {
      question: "This will DELETE 15 branches and merge to main. Continue?",
      header: "Destructive Op",
      options: [
        {
          label: "Proceed",
          description: "Delete branches (CANNOT BE UNDONE)"
        },
        {
          label: "Dry Run",
          description: "Show what would be deleted"
        },
        {
          label: "Cancel",
          description: "Abort entire process"
        }
      ]
    }
  ]
});

if (answer["Destructive Op"] === "Proceed") {
  // Require additional final confirmation
  const final = await AskUserQuestion({
    questions: [
      {
        question: "Type DELETE to confirm irreversible action:",
        header: "Final Confirmation"
      }
    ]
  });
  
  if (final["Final Confirmation"] === "DELETE") {
    executeDeletion();
  }
}

---

📋 Key Constraints (TUI Optimization)

Constraint	Reason	Example
1-4 questions max	Avoid user fatigue	Use follow-up surveys instead
2-4 options per Q	Prevent choice overload	Avoid 5+ options (decision paralysis)
Header ≤12 chars	TUI layout fit	"DB Choice" not "Which Database Technology"
Label 1-5 words	Quick scanning	"PostgreSQL" not "SQL Database by PostgreSQL"
Description required	Enables informed choice	Always explain trade-offs
Auto "Other" option	Always available	System adds automatically for custom input
No HTML/markdown	Plain text TUI	Use formatting sparingly
Language matching	User experience	Always match configured conversation_language

---

🔄 Integration with Alfred Sub-agents

Sub-agent	When to Ask	Example Trigger	Questions
spec-builder (/alfred:1-plan)	SPEC title vague, scope undefined	"Add feature" without specifics	"Feature type?", "Scope?", "Users affected?"
tdd-implementer (/alfred:2-run)	Implementation approach unclear	Multiple valid implementation paths	"Architecture?", "Libraries?", "Constraints?"
doc-syncer (/alfred:3-sync)	Sync scope unclear	Full vs partial sync decision	"Full sync?", "Which files?", "Auto-commit?"
qa-validator	Review depth unclear	Quick vs comprehensive check	"Review level?", "Security focus?", "Performance?"

---

🎓 Top 10 Usage Patterns

Pattern 1: Feature Type Clarification

Trigger: "Add dashboard feature" without specifics
Question: "Which dashboard type: Analytics, Admin, or Profile?"
Outcome: Narrowed scope → faster implementation

Pattern 2: Implementation Approach Selection

Trigger: Multiple valid tech choices
Question: "JWT tokens, session-based, or OAuth?"
Outcome: Locked architecture → deterministic development

Pattern 3: Risky Operation Confirmation

Trigger: Destructive action (delete, migrate, reset)
Question: "This will delete X. Proceed?" with retry confirmation
Outcome: Explicit consent + audit trail

Pattern 4: Multi-Feature Selection

Trigger: "Which features to enable?"
Question: Multi-select of independent features
Outcome: Precise feature set → no scope creep

Pattern 5: Sequential Conditional Decisions

Trigger: Dependent choices (Q2 depends on Q1)
Question: First survey → follow-up based on answer
Outcome: Progressive narrowing → precise specification

Pattern 6: Technology Stack Selection

Trigger: "Build with what stack?"
Question: Database, cache, queue, API type
Outcome: Full stack locked → team alignment

Pattern 7: Performance vs Reliability

Trigger: Trade-off between conflicting goals
Question: "Optimize for speed, reliability, or cost?"
Outcome: Explicit requirements → informed trade-offs

Pattern 8: Custom Input Handling

Trigger: "Other" option selected
Question: "Please describe..." with validation
Outcome: Unexpected inputs handled gracefully

Pattern 9: Experience Level Calibration

Trigger: Unclear target audience
Question: "Beginner, intermediate, or advanced?"
Outcome: Content adapted to expertise level

Pattern 10: Approval Workflow

Trigger: Major decision needs consensus
Question: Multi-team approval with options
Outcome: Documented decision with stakeholder buy-in

---

✅ Best Practices Summary

DO's

• Be specific: "Which database type?" not "What should we use?"
• Provide context: Include file names, scope, or impact
• Order logically: General → Specific; safest option first
• Flag risks: Use "NOT RECOMMENDED" or "CAUTION:" prefixes
• Explain trade-offs: Mention time, resources, complexity, performance
• Limit options: 2-4 per question (not 5+ for decision paralysis)
• Validate custom input: Check "Other" responses for validity
• Batch related Q's: Keep related decisions together (max 4 questions)

DON'Ts

• Overuse questions: Only ask when genuinely ambiguous
• Too many options: 5+ options cause decision paralysis
• Vague labels: "Option A", "Use tokens", "Option 2"
• Skip descriptions: User needs rationale for informed choice
• Hide trade-offs: Always mention implications and costs
• Ask for obvious: Single clear path = no question needed
• Recursive surveys: Avoid asking the same question twice
• Ignore language: Always match user's configured conversation_language

---

🔗 Related Skills

• moai-core-personas (Communication styles by user level)
• moai-core-spec-authoring (SPEC clarity & structure)
• moai-foundation-specs (SPEC format & requirements)
• moai-core-language-detection (Conversation language handling)

---

📚 Quick Reference Card

Scenario	Action	Key Points
Vague request	Ask for clarification	1-4 questions max
Multiple approaches	Let user choose	Show trade-offs clearly
Risky operation	Get explicit consent	Require final confirmation
Feature selection	Use multi-select	Independent options only
Dependent decisions	Use sequential surveys	Ask follow-ups based on answers
Custom input	Validate carefully	Re-ask if invalid
Accessibility	Plain text UI	No complex formatting

---

Token Budget Optimization

• Average per survey: 500-800 tokens
• Typical workflow: 1-2 surveys per task (1,000-1,600 tokens total)
• Benefit: Eliminates 3-5 clarification rounds (3,000-5,000 tokens saved)
• ROI: Net savings of 1,400-3,500 tokens per interaction

---

For detailed API specifications: reference.md
For real-world examples: examples.md
Last Updated: 2025-11-18
Status: Production Ready (Enterprise )