moai-adk 0.5.4__py3-none-any.whl → 0.5.6__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-alfred-interactive-questions/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: moai-alfred-interactive-questions
-version: 3.0.0
+version: 3.1.0
 created: 2025-10-22
-updated: 2025-10-23
+updated: 2025-10-27
 status: active
 description: Guide Alfred sub-agents to actively invoke AskUserQuestion for ambiguous decisions.
 keywords: ['interactive', 'clarification', 'decision-making', 'AskUserQuestion']
@@ -17,7 +17,7 @@ allowed-tools:
 | Field | Value |
 | ----- | ----- |
 | **Skill Name** | moai-alfred-interactive-questions |
-| **Version** | 3.0.0 (2025-10-23) |
+| **Version** | 3.1.0 (2025-10-27) |
 | **Core Tool** | `AskUserQuestion` (Claude Code built-in) |
 | **Auto-load** | When Alfred detects ambiguity in requests |
 | **Tier** | Alfred (Workflow Orchestration) |
@@ -82,9 +82,7 @@ Proceed with confirmed specifications
 
 ---
 
-## AskUserQuestion API Reference
-
-### Minimal Invocation
+## Quick Start: Minimal Invocation
 
 ```typescript
 const answer = await AskUserQuestion({
@@ -110,7 +108,9 @@ const answer = await AskUserQuestion({
 // Returns: { "Approach": "Option 1" }
 ```
 
-### Key Constraints
+---
+
+## Key Constraints
 
 | Constraint | Reason |
 |-----------|--------|
@@ -121,292 +121,58 @@ const answer = await AskUserQuestion({
 | **Description required** | Enables informed choice |
 | **Auto "Other" option** | Always available for custom input |
 
-### Question Types
-
-**Single-Select** (`multiSelect: false`):
-- Mutually exclusive: "Choose ONE database"
-- Returns: `{ "Header": "Selected Label" }`
-
-**Multi-Select** (`multiSelect: true`):
-- Independent options: "Which features to enable?" (check multiple)
-- Returns: `{ "Header": ["Label1", "Label2"] }`
-
 ---
 
-## Usage Patterns (Top 5)
+## Top 5 Usage Patterns
 
 ### Pattern 1: Implementation Approach
-
 **Trigger**: "Add feature X" or "Build Y" without specifics
 
-```typescript
-await AskUserQuestion({
-  questions: [{
-    question: "How should we implement this feature?",
-    header: "Approach",
-    multiSelect: false,
-    options: [
-      { label: "New standalone component", description: "Isolated, reusable." },
-      { label: "Extend existing component", description: "Shared state, simpler." },
-      { label: "Use environment flag", description: "Conditional visibility." }
-    ]
-  }]
-});
-```
-
 ### Pattern 2: Confirmation (Risky Operations)
-
 **Trigger**: Destructive action (delete, migrate, reset)
 
-```typescript
-await AskUserQuestion({
-  questions: [{
-    question: "This will permanently delete 50 records. Proceed?",
-    header: "Confirm",
-    multiSelect: false,
-    options: [
-      { label: "Yes, proceed", description: "Irreversible. Continue." },
-      { label: "No, cancel", description: "Abort operation." }
-    ]
-  }]
-});
-```
-
 ### Pattern 3: Multi-Option Feature Selection
-
 **Trigger**: "Which framework/library/approach?"
 
-```typescript
-await AskUserQuestion({
-  questions: [{
-    question: "Which i18n library?",
-    header: "Library",
-    multiSelect: false,
-    options: [
-      { label: "next-intl", description: "Next.js 15+ native, best DX." },
-      { label: "react-i18next", description: "Popular, flexible, more setup." },
-      { label: "Format.js", description: "ICU format, powerful, complex." }
-    ]
-  }]
-});
-```
-
 ### Pattern 4: Multi-Select (Independent Features)
-
 **Trigger**: "Which features to enable/include?"
 
-```typescript
-await AskUserQuestion({
-  questions: [{
-    question: "Which testing frameworks?",
-    header: "Test Tools",
-    multiSelect: true,  // Multiple selections allowed
-    options: [
-      { label: "Unit tests (Vitest)", description: "Fast, modern." },
-      { label: "E2E tests (Playwright)", description: "Browser automation." },
-      { label: "Visual regression", description: "Screenshot comparison." }
-    ]
-  }]
-});
-```
-
 ### Pattern 5: Sequential Questions (Conditional Flow)
-
 **Trigger**: Dependent decisions (Q2 depends on Q1 answer)
 
-```typescript
-// Question 1
-const q1 = await AskUserQuestion({
-  questions: [{
-    question: "Enable authentication?",
-    header: "Auth",
-    options: [
-      { label: "Yes", description: "User login required." },
-      { label: "No", description: "Public access." }
-    ]
-  }]
-});
+> **Detailed examples and code**: See [examples.md](examples.md)
 
-// Question 2 (only if Q1 = "Yes")
-if (q1["Auth"] === "Yes") {
-  const q2 = await AskUserQuestion({
-    questions: [{
-      question: "Which auth provider?",
-      header: "Provider",
-      options: [
-        { label: "JWT + email", description: "Traditional." },
-        { label: "OAuth", description: "Third-party." }
-      ]
-    }]
-  });
-}
-```
+---
+
+## Integration with Alfred Sub-agents
+
+| Sub-agent | When to Ask | Example Trigger |
+|-----------|-------------|-----------------|
+| **spec-builder** (`/alfred:1-plan`) | SPEC title vague, scope undefined | "Add feature" without specifics |
+| **code-builder** (`/alfred:2-run`) | Implementation approach unclear | Multiple valid implementation paths |
+| **doc-syncer** (`/alfred:3-sync`) | Sync scope unclear | Full vs partial sync decision |
+
+> **Detailed integration patterns**: See [reference.md](reference.md)
 
 ---
 
-## Best Practices
+## Best Practices Summary
 
 ### ✅ DO
-
 - **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
-- **Single-select for exclusive**: "Choose ONE"
-- **Multi-select for combinable**: "Check any that apply"
-- **Include descriptions**: Every option needs rationale
-- **Keep headers short**: "Approach" not "Implementation Strategy"
-- **Batch related questions**: Ask 2-3 at once if they flow naturally
 
 ### ❌ DON'T
-
 - **Overuse questions**: Only ask when ambiguous
 - **Too many options**: 2-4 per question max
 - **Vague labels**: "Option A", "Use tokens", "Option 2"
 - **Skip descriptions**: User needs rationale
 - **Hide trade-offs**: Always mention implications
-- **Make destructive default**: Risky option = NOT pre-selected
-- **Mix concerns**: One decision per question
-- **Manually add "Other"**: It's auto-provided
-- **Nest more than 2 levels deep**: Keep flow linear
-
----
 
-## Integration with Alfred Sub-agents
-
-### spec-builder (`/alfred:1-plan`)
-
-**When to ask**:
-- SPEC title is vague ("Add feature")
-- Scope undefined (what exactly?)
-- Domain prefix unclear (AUTH vs UI vs DATA?)
-
-**Example**:
-```typescript
-if (titleIsAmbiguous(specTitle)) {
-  const answer = await AskUserQuestion({
-    questions: [{
-      question: "Can you clarify what this SPEC should cover?",
-      header: "Scope",
-      options: [...]
-    }]
-  });
-  specTitle = answer["Scope"];
-}
-```
-
-### code-builder (`/alfred:2-run`)
-
-**When to ask**:
-- Implementation approach unclear
-- Multiple valid paths exist
-- Error recovery needed (failing tests)
-
-**Example**:
-```typescript
-if (multipleValidImplementationPaths) {
-  const answer = await AskUserQuestion({
-    questions: [{
-      question: "How should we implement this?",
-      header: "Approach",
-      options: [...]
-    }]
-  });
-  implementationStrategy = answer["Approach"];
-}
-```
-
-### doc-syncer (`/alfred:3-sync`)
-
-**When to ask**:
-- Sync scope unclear (full vs partial)
-- PR Ready status uncertain
-- Documentation coverage decision needed
-
-**Example**:
-```typescript
-const syncMode = await AskUserQuestion({
-  questions: [{
-    question: "Which sync mode?",
-    header: "Mode",
-    options: [
-      { label: "auto", description: "Smart detection." },
-      { label: "force", description: "Regenerate all." }
-    ]
-  }]
-});
-```
-
----
-
-## Real-World Examples
-
-### Example: Vague Feature Request
-
-**User**: "Add a completion page for the competition."
-
-**Alfred detects ambiguity**:
-- Where should it live? (new route vs modify existing)
-- Who can access it? (public vs authenticated)
-- What should it display? (results vs simple message)
-
-**AskUserQuestion invocation**:
-```typescript
-const answer = await AskUserQuestion({
-  questions: [
-    {
-      question: "How should the completion page be implemented?",
-      header: "Approach",
-      multiSelect: false,
-      options: [
-        { label: "New public route", description: "New page visible to all visitors." },
-        { label: "Modify existing page", description: "Add conditional logic to /end page." },
-        { label: "Environment flag", description: "Set NEXT_PUBLIC_COMPETITION_CLOSED=true." }
-      ]
-    },
-    {
-      question: "For logged-in participants?",
-      header: "Behavior",
-      multiSelect: false,
-      options: [
-        { label: "Show full results", description: "Redirect to /end page with history." },
-        { label: "Show simple message", description: "Display 'Competition concluded' only." }
-      ]
-    }
-  ]
-});
-```
-
-**Result**: Alfred knows exactly what to build.
-
----
-
-## Anti-Patterns to Avoid
-
-### ❌ Too Many Options
-```typescript
-// 8+ options = choice paralysis
-options: [
-  { label: "PostgreSQL" }, { label: "MySQL" }, { label: "MariaDB" },
-  { label: "SQLite" }, { label: "MongoDB" }, { label: "CouchDB" },
-  { label: "Cassandra" }, { label: "Redis" }
-]
-```
-
-### ✅ Group Options
-```typescript
-// First ask: which TYPE? Then: specific within type
-questions: [{
-  question: "Database type?",
-  header: "DB Type",
-  options: [
-    { label: "Relational (SQL)", description: "PostgreSQL, MySQL, etc." },
-    { label: "Document (NoSQL)", description: "MongoDB, CouchDB, etc." },
-    { label: "Key-Value", description: "Redis, Memcached, etc." }
-  ]
-}]
-```
+> **Complete best practices guide**: See [reference.md](reference.md)
 
 ---
 
@@ -427,35 +193,21 @@ try {
 const answer = await AskUserQuestion({...});
 
 if (answer["Header"] === "Other" || !VALID_OPTIONS.includes(answer["Header"])) {
-  // Handle custom input validation
   validateCustomInput(answer["Header"]);
 }
 ```
 
 ---
 
-## Performance Tips
-
-- **Batch questions**: Ask 2-3 related questions in one call
-- **Minimize calls**: Don't ask sequentially unless truly dependent
-- **Pre-generate options**: Analyze codebase once to generate all options
-
----
-
-## References
-
-**Official Claude Code Documentation**:
-- AskUserQuestion tool (built-in Claude Code)
-- Interactive Prompting (CLAUDE.md § Clarification & Interactive Prompting)
+## Related Skills
 
-**Related Skills**:
 - `moai-alfred-spec-metadata-validation` (SPEC clarity)
 - `moai-alfred-ears-authoring` (requirement phrasing)
 - `moai-foundation-specs` (SPEC structure)
 
 ---
 
-## Summary
+## Quick Reference
 
 **When to use**:
 - User intent is ambiguous
@@ -477,4 +229,9 @@ if (answer["Header"] === "Other" || !VALID_OPTIONS.includes(answer["Header"])) {
 
 ---
 
-**End of Skill** | Refactored 2025-10-23
+**For detailed API specifications**: [reference.md](reference.md)  
+**For real-world examples**: [examples.md](examples.md)
+
+---
+
+**End of Skill** | Refactored 2025-10-27