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

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

@@ -1,34 +1,22 @@
-# moai-alfred-interactive-questions - Working Examples
+# Alfred Interactive Questions - Real-World Examples
 
-_Last updated: 2025-10-23_
+> **Main Skill**: [SKILL.md](SKILL.md)  
+> **API Reference**: [reference.md](reference.md)
 
-## Example 1: Simple Confirmation
+---
 
-**Scenario**: Destructive operation (delete 50 user records)
+## Example 1: Vague Feature Request
 
-```typescript
-const answer = await AskUserQuestion({
-  questions: [{
-    question: "This will permanently delete 50 user records. Continue?",
-    header: "Confirm",
-    multiSelect: false,
-    options: [
-      { label: "Yes, proceed", description: "Irreversible operation. Delete now." },
-      { label: "No, cancel", description: "Abort and return." }
-    ]
-  }]
-});
+### Scenario
 
-if (answer["Confirm"] === "Yes, proceed") {
-  // Execute deletion
-}
-```
-
----
+**User**: "Add a completion page for the competition."
 
-## Example 2: Implementation Approach
+**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)
 
-**Scenario**: "Add a completion page" (vague)
+### AskUserQuestion Invocation
 
 ```typescript
 const answer = await AskUserQuestion({
@@ -38,220 +26,590 @@ const answer = await AskUserQuestion({
       header: "Approach",
       multiSelect: false,
       options: [
-        { label: "New public route", description: "Separate page at /competition-closed" },
-        { label: "Modify /end page", description: "Add conditional logic to existing page" },
-        { label: "Environment flag", description: "Use NEXT_PUBLIC_COMPETITION_CLOSED" }
+        { 
+          label: "New public route", 
+          description: "New page at /competition-complete, visible to all visitors." 
+        },
+        { 
+          label: "Modify existing page", 
+          description: "Add conditional logic to existing /end page based on competition status." 
+        },
+        { 
+          label: "Environment flag", 
+          description: "Set NEXT_PUBLIC_COMPETITION_CLOSED=true to show message on homepage." 
+        }
       ]
     },
     {
-      question: "For logged-in participants?",
+      question: "For logged-in participants, what should they see?",
       header: "Behavior",
       multiSelect: false,
       options: [
-        { label: "Show results", description: "Redirect to /end with full history" },
-        { label: "Show message", description: "'Competition concluded' only" }
+        { 
+          label: "Show full results", 
+          description: "Redirect to /end page with their submission history and rankings." 
+        },
+        { 
+          label: "Show simple message", 
+          description: "Display 'Competition concluded. Thank you for participating!' only." 
+        }
       ]
     }
   ]
 });
 
-const approach = answer["Approach"];
-const behavior = answer["Behavior"];
-// Proceed with confirmed specifications
+// Result:
+// {
+//   "Approach": "New public route",
+//   "Behavior": "Show full results"
+// }
+```
+
+### Outcome
+
+Alfred now knows **exactly** what to build:
+- Create `/app/competition-complete/page.tsx`
+- New public route
+- Logged-in users redirected to `/end` page with full results
+- Non-logged-in users see simple completion message
+
+---
+
+## Example 2: Implementation Approach (Pattern 1)
+
+### Scenario
+
+**User**: "Add i18n support to the app."
+
+**Alfred detects**:
+- Multiple valid i18n libraries exist
+- Each has different trade-offs (DX, complexity, performance)
+- User hasn't specified preference
+
+### AskUserQuestion Invocation
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "Which i18n library should we use for Next.js 15?",
+    header: "Library",
+    multiSelect: false,
+    options: [
+      { 
+        label: "next-intl", 
+        description: "Native Next.js 15 support, best DX, automatic type safety." 
+      },
+      { 
+        label: "react-i18next", 
+        description: "Most popular, flexible, more setup required, larger bundle." 
+      },
+      { 
+        label: "Format.js", 
+        description: "ICU message format, powerful pluralization, steeper learning curve." 
+      }
+    ]
+  }]
+});
+
+// Result: { "Library": "next-intl" }
+```
+
+### Outcome
+
+Alfred proceeds with `next-intl`, avoiding:
+- ❌ Guessing wrong library
+- ❌ Implementing then refactoring later
+- ❌ 3-5 rounds of "actually, can we use X instead?"
+
+---
+
+## Example 3: Risky Operation Confirmation (Pattern 2)
+
+### Scenario
+
+**User**: "Delete all test users from production database."
+
+**Alfred detects**:
+- Destructive operation (data loss)
+- Production environment (high risk)
+- Explicit confirmation required
+
+### AskUserQuestion Invocation
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "⚠️ This will PERMANENTLY delete 50 test users from PRODUCTION database. Are you sure?",
+    header: "Confirm",
+    multiSelect: false,
+    options: [
+      { 
+        label: "No, cancel", 
+        description: "Abort operation. No changes will be made." 
+      },
+      { 
+        label: "Yes, proceed", 
+        description: "🚨 IRREVERSIBLE. Delete 50 users now." 
+      }
+    ]
+  }]
+});
+
+// Result: { "Confirm": "No, cancel" } (user cancelled)
 ```
 
+### Outcome
+
+Alfred **aborts** operation without executing destructive command. User explicitly chose to cancel after seeing full risk disclosure.
+
 ---
 
-## Example 3: Multi-Select (Independent Features)
+## Example 4: Multi-Select Feature Selection (Pattern 4)
 
-**Scenario**: "Which testing frameworks?"
+### Scenario
+
+**User**: "Set up testing for the new project."
+
+**Alfred detects**:
+- Multiple testing frameworks can coexist
+- User might want unit + E2E + visual testing
+- No explicit preference stated
+
+### AskUserQuestion Invocation
 
 ```typescript
 const answer = await AskUserQuestion({
   questions: [{
-    question: "Which testing frameworks to include?",
+    question: "Which testing frameworks should we set up? (Select all that apply)",
     header: "Test Tools",
-    multiSelect: true,  // User can select multiple
+    multiSelect: true,  // Multiple selections allowed
     options: [
-      { label: "Unit tests (Vitest)", description: "Fast unit testing." },
-      { label: "E2E tests (Playwright)", description: "Browser automation." },
-      { label: "Visual regression", description: "Screenshot comparison." }
+      { 
+        label: "Unit tests (Vitest)", 
+        description: "Fast, modern, Vite-native. ~2min setup." 
+      },
+      { 
+        label: "E2E tests (Playwright)", 
+        description: "Browser automation, cross-browser. ~10min setup." 
+      },
+      { 
+        label: "Visual regression", 
+        description: "Screenshot comparison with Playwright. ~5min setup." 
+      }
     ]
   }]
 });
 
-const selectedTools = answer["Test Tools"];  // ["Unit tests (Vitest)", "E2E tests (Playwright)"]
-// Install selected frameworks
+// Result: { "Test Tools": ["Unit tests (Vitest)", "E2E tests (Playwright)"] }
 ```
 
+### Outcome
+
+Alfred installs and configures:
+- ✅ Vitest for unit tests
+- ✅ Playwright for E2E tests
+- ❌ Skips visual regression (not selected)
+
 ---
 
-## Example 4: Sequential Questions (Conditional)
+## Example 5: Sequential Questions (Conditional Flow, Pattern 5)
 
-**Scenario**: Q2 depends on Q1 answer
+### Scenario
+
+**User**: "Add authentication to the app."
+
+**Alfred detects**:
+- First decision: Enable auth? (Yes/No)
+- Second decision: If yes, which provider? (depends on Q1)
+
+### AskUserQuestion Invocation (Part 1)
 
 ```typescript
-// Question 1
+// Question 1: Enable authentication?
 const q1 = await AskUserQuestion({
   questions: [{
-    question: "Enable authentication?",
+    question: "Should we enable user authentication?",
     header: "Auth",
+    multiSelect: false,
     options: [
-      { label: "Yes", description: "User login required." },
-      { label: "No", description: "Public access." }
+      { 
+        label: "Yes", 
+        description: "User login required for protected routes." 
+      },
+      { 
+        label: "No", 
+        description: "Public access only, no authentication." 
+      }
     ]
   }]
 });
 
-// Question 2 (only if Q1 = "Yes")
+// Result: { "Auth": "Yes" }
+```
+
+### AskUserQuestion Invocation (Part 2, Conditional)
+
+```typescript
+// Question 2: Only ask if Q1 = "Yes"
 if (q1["Auth"] === "Yes") {
   const q2 = await AskUserQuestion({
     questions: [{
-      question: "Which auth provider?",
+      question: "Which authentication provider?",
       header: "Provider",
+      multiSelect: false,
       options: [
-        { label: "JWT + email", description: "Traditional email/password." },
-        { label: "OAuth", description: "Third-party login (Google, GitHub)." }
+        { 
+          label: "JWT + email", 
+          description: "Traditional email/password with JWT tokens. ~30min setup." 
+        },
+        { 
+          label: "OAuth (Google)", 
+          description: "Third-party login via Google. Faster for users. ~20min setup." 
+        },
+        { 
+          label: "SAML", 
+          description: "Enterprise SSO (for corporate environments). ~2hr setup." 
+        }
       ]
     }]
   });
-
-  const provider = q2["Provider"];
-  // Setup authentication
+  
+  // Result: { "Provider": "OAuth (Google)" }
 }
 ```
 
+### Outcome
+
+Alfred implements:
+- ✅ Authentication enabled
+- ✅ OAuth with Google provider
+- ✅ Skips JWT setup (not selected)
+- ❌ If Q1 was "No", Q2 never asked (saves time)
+
 ---
 
-## Example 5: Feature Selection
+## Example 6: Option Grouping (Hierarchical Selection)
+
+### Scenario
+
+**User**: "Set up a database for the project."
 
-**Scenario**: "Which i18n library?"
+**Alfred detects**:
+- 8+ database options exist
+- Too many for one question → choice paralysis
+- Need hierarchical selection: Category → Specific
+
+### AskUserQuestion Invocation (Step 1: Category)
 
 ```typescript
-const answer = await AskUserQuestion({
+// Step 1: Narrow by database type
+const category = await AskUserQuestion({
   questions: [{
-    question: "Which i18n library?",
-    header: "Library",
+    question: "What type of database does your project need?",
+    header: "DB Type",
     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, complex but powerful." }
+      { 
+        label: "Relational (SQL)", 
+        description: "PostgreSQL, MySQL, SQLite. ACID guarantees, structured data." 
+      },
+      { 
+        label: "Document (NoSQL)", 
+        description: "MongoDB, CouchDB. Flexible schema, JSON documents." 
+      },
+      { 
+        label: "Key-Value", 
+        description: "Redis, Memcached. In-memory cache, fast reads." 
+      }
     ]
   }]
 });
 
-const library = answer["Library"];  // "next-intl"
-// Install and configure library
+// Result: { "DB Type": "Relational (SQL)" }
+```
+
+### AskUserQuestion Invocation (Step 2: Specific Choice)
+
+```typescript
+// Step 2: Specific database within category
+if (category["DB Type"] === "Relational (SQL)") {
+  const specific = await AskUserQuestion({
+    questions: [{
+      question: "Which SQL database?",
+      header: "SQL DB",
+      multiSelect: false,
+      options: [
+        { 
+          label: "PostgreSQL", 
+          description: "Advanced features (JSON, full-text search, extensions). Industry standard." 
+        },
+        { 
+          label: "MySQL", 
+          description: "Most popular, wide hosting support, good performance." 
+        },
+        { 
+          label: "SQLite", 
+          description: "Embedded, serverless, single-file. Good for prototypes and small apps." 
+        }
+      ]
+    }]
+  });
+  
+  // Result: { "SQL DB": "PostgreSQL" }
+}
+```
+
+### Outcome
+
+Alfred avoids:
+- ❌ Presenting 8 options at once (choice paralysis)
+- ❌ User confusion ("What's the difference between MariaDB and MySQL?")
+
+Instead:
+- ✅ First narrows to category (3 options)
+- ✅ Then presents specific choices within category (3 options)
+- ✅ Clear, manageable decision flow
+
+---
+
+## Example 7: Batch Related Questions
+
+### Scenario
+
+**User**: "Initialize a new Next.js project with best practices."
+
+**Alfred detects**:
+- Multiple independent decisions needed
+- All decisions are related to project setup
+- Can ask 3 questions at once (no dependencies)
+
+### AskUserQuestion Invocation
+
+```typescript
+const answers = await AskUserQuestion({
+  questions: [
+    {
+      question: "Which database?",
+      header: "Database",
+      multiSelect: false,
+      options: [
+        { label: "PostgreSQL", description: "Relational, ACID-compliant, advanced features." },
+        { label: "MongoDB", description: "Document store, flexible schema, rapid prototyping." }
+      ]
+    },
+    {
+      question: "Which testing frameworks? (Select all that apply)",
+      header: "Testing",
+      multiSelect: true,  // Multiple selections allowed
+      options: [
+        { label: "Unit tests", description: "Vitest for fast unit testing." },
+        { label: "E2E tests", description: "Playwright for browser automation." },
+        { label: "Visual tests", description: "Screenshot comparison testing." }
+      ]
+    },
+    {
+      question: "Enable TypeScript strict mode?",
+      header: "TypeScript",
+      multiSelect: false,
+      options: [
+        { label: "Yes (recommended)", description: "Strict type checking, catch errors early." },
+        { label: "No", description: "Loose type checking, faster initial development." }
+      ]
+    }
+  ]
+});
+
+// Result:
+// {
+//   "Database": "PostgreSQL",
+//   "Testing": ["Unit tests", "E2E tests"],
+//   "TypeScript": "Yes (recommended)"
+// }
 ```
 
+### Outcome
+
+Alfred configures project with:
+- ✅ PostgreSQL database
+- ✅ Vitest unit tests
+- ✅ Playwright E2E tests
+- ❌ No visual regression tests
+- ✅ TypeScript strict mode enabled
+
+All decided in **one interaction** instead of 3 separate back-and-forth exchanges.
+
 ---
 
-## Example 6: Error Recovery
+## Example 8: Error Recovery After Test Failure
+
+### Scenario
 
-**Scenario**: 3 tests failed, ask how to proceed
+**Context**: Alfred is in `/alfred:2-run` phase, tests are failing.
+
+**Alfred detects**:
+- Tests fail after implementation
+- Multiple possible fixes exist
+- User input needed to decide repair strategy
+
+### AskUserQuestion Invocation
 
 ```typescript
 const answer = await AskUserQuestion({
   questions: [{
-    question: "3 tests failed in auth.test.ts. How should we proceed?",
-    header: "Test Failure",
+    question: "Tests are failing. How should we proceed?",
+    header: "Fix Strategy",
     multiSelect: false,
     options: [
-      { label: "Debug immediately", description: "Stop and fix now." },
-      { label: "Skip tests", description: "NOT RECOMMENDED - continues with failing tests." },
-      { label: "Rollback changes", description: "Revert to last passing commit." }
+      { 
+        label: "Fix implementation", 
+        description: "Adjust code to pass existing tests (tests are correct)." 
+      },
+      { 
+        label: "Update tests", 
+        description: "Modify tests to match new implementation (implementation is correct)." 
+      },
+      { 
+        label: "Debug together", 
+        description: "Review both implementation and tests to identify root cause." 
+      }
     ]
   }]
 });
 
-if (answer["Test Failure"] === "Debug immediately") {
-  // Trigger debug workflow
-} else if (answer["Test Failure"] === "Rollback changes") {
-  // Rollback git changes
-}
+// Result: { "Fix Strategy": "Fix implementation" }
 ```
 
----
+### Outcome
 
-## Example 7: /alfred:1-plan Integration
+Alfred:
+- ✅ Keeps tests unchanged
+- ✅ Fixes implementation to satisfy test expectations
+- ✅ Avoids "test modification to make them pass" anti-pattern
+- ✅ Follows RED → GREEN → REFACTOR TDD cycle correctly
 
-**Scenario**: spec-builder detects ambiguous SPEC title
+---
 
-```typescript
-// Inside spec-builder
-function shouldAskForClarification(title: string): boolean {
-  return title.length < 20 || title.includes("feature/add/implement");
-}
+## Example 9: SPEC Scope Clarification (spec-builder)
 
-if (shouldAskForClarification(userTitle)) {
-  const answer = await AskUserQuestion({
-    questions: [{
-      question: "Can you clarify what this SPEC should cover?",
-      header: "Scope",
-      options: [
-        { label: "Authentication system", description: "User login, JWT tokens, refresh logic." },
-        { label: "UI components", description: "Reusable components library." },
-        { label: "API endpoints", description: "REST API implementation." }
-      ]
-    }]
-  });
+### Scenario
 
-  specTitle = answer["Scope"];
-}
-```
-
----
+**User**: "Create SPEC for performance improvements."
 
-## Example 8: /alfred:2-run Integration
+**Alfred detects** (spec-builder sub-agent):
+- SPEC title is vague ("performance improvements")
+- Scope undefined (backend? frontend? database?)
+- Multiple domains affected
 
-**Scenario**: code-builder detects multiple implementation paths
+### AskUserQuestion Invocation
 
 ```typescript
-// Inside code-builder
-if (multipleValidImplementationPaths) {
-  const answer = await AskUserQuestion({
-    questions: [{
-      question: "How should we implement JWT storage?",
-      header: "Storage",
+const answer = await AskUserQuestion({
+  questions: [
+    {
+      question: "Which area needs performance improvements?",
+      header: "Domain",
+      multiSelect: false,
       options: [
-        { label: "HttpOnly cookie", description: "Most secure, no JS access." },
-        { label: "LocalStorage", description: "Accessible but vulnerable to XSS." },
-        { label: "Memory + refresh", description: "Balance between security and UX." }
+        { label: "Backend API", description: "Optimize API response times, database queries." },
+        { label: "Frontend", description: "Improve page load times, bundle size, rendering." },
+        { label: "Database", description: "Add indexes, optimize queries, caching." },
+        { label: "All of the above", description: "Comprehensive performance audit." }
       ]
-    }]
-  });
+    },
+    {
+      question: "What's the performance target?",
+      header: "Target",
+      multiSelect: false,
+      options: [
+        { label: "< 200ms API", description: "API responses under 200ms (P95)." },
+        { label: "< 2s page load", description: "Pages load under 2 seconds (P95)." },
+        { label: "< 100ms queries", description: "Database queries under 100ms (P95)." }
+      ]
+    }
+  ]
+});
 
-  const storageStrategy = answer["Storage"];
-  implementWithStrategy(storageStrategy);
-}
+// Result:
+// {
+//   "Domain": "Backend API",
+//   "Target": "< 200ms API"
+// }
 ```
 
+### Outcome
+
+spec-builder generates precise SPEC:
+- ✅ Title: `[PERF-001] Optimize Backend API Response Times to <200ms`
+- ✅ Scope: Backend API performance only
+- ✅ Clear success criteria: P95 latency < 200ms
+- ❌ Avoids vague SPEC like "Improve performance"
+
 ---
 
-## Example 9: /alfred:3-sync Integration
+## Example 10: Doc Sync Mode Selection (doc-syncer)
+
+### Scenario
+
+**User**: "Sync documentation."
+
+**Alfred detects** (doc-syncer sub-agent):
+- Sync mode unclear (auto-detect vs force-regenerate vs partial)
+- User hasn't specified preference
+- Different modes have different time/accuracy trade-offs
 
-**Scenario**: doc-syncer asks about sync mode
+### AskUserQuestion Invocation
 
 ```typescript
-// Inside doc-syncer
 const answer = await AskUserQuestion({
   questions: [{
-    question: "Which sync mode?",
-    header: "Mode",
+    question: "Which documentation sync mode?",
+    header: "Sync Mode",
     multiSelect: false,
     options: [
-      { label: "auto", description: "Smart detection, sync affected docs only." },
-      { label: "force", description: "Regenerate all docs from scratch." },
-      { label: "status", description: "Show status without making changes." }
+      { 
+        label: "auto", 
+        description: "Smart detection of changes. Fast, minimal updates. (Recommended)" 
+      },
+      { 
+        label: "force", 
+        description: "Regenerate ALL documentation. Slow but guaranteed accurate." 
+      },
+      { 
+        label: "partial", 
+        description: "Update only specified sections. Fast, targeted." 
+      }
     ]
   }]
 });
 
-const syncMode = answer["Mode"];
-runSync(syncMode);
+// Result: { "Sync Mode": "auto" }
 ```
 
+### Outcome
+
+doc-syncer:
+- ✅ Uses auto-detection mode
+- ✅ Only updates changed sections
+- ✅ Faster execution (1-2 min vs 10 min for force mode)
+- ✅ User sees clear time/accuracy trade-off before deciding
+
+---
+
+## Summary: Pattern Catalog
+
+| Pattern | Use Case | Example Scenario |
+|---------|----------|------------------|
+| **Pattern 1: Implementation Approach** | Multiple valid implementation paths | "Add i18n support" (which library?) |
+| **Pattern 2: Confirmation** | Risky/destructive operations | "Delete production data" (are you sure?) |
+| **Pattern 3: Multi-Option Selection** | Choose ONE from multiple frameworks/tools | "Which testing framework?" |
+| **Pattern 4: Multi-Select** | Enable/disable independent features | "Which features to enable?" (check multiple) |
+| **Pattern 5: Sequential Questions** | Q2 depends on Q1 answer | "Enable auth?" → If yes, "Which provider?" |
+| **Pattern 6: Option Grouping** | Too many options → hierarchical selection | Database type → Specific database |
+| **Pattern 7: Batch Questions** | Multiple independent decisions | Project setup (DB + Testing + TypeScript) |
+| **Pattern 8: Error Recovery** | Handle failures with user guidance | Test failure → Fix implementation vs update tests |
+| **Pattern 9: SPEC Clarification** | Vague SPEC scope/title | "Performance improvements" → Which domain? |
+| **Pattern 10: Mode Selection** | Choose workflow mode/strategy | Doc sync mode (auto vs force vs partial) |
+
 ---
 
-For detailed guidance, see **SKILL.md** and **reference.md**
+**End of Examples** | 2025-10-27