aiskillstore/interactive-planner

Interactive Planner

Purpose

Leverage Claude Code's AskUserQuestion tool to systematically gather project requirements through structured, interactive questions with multiple choice and multi-select options.

Specialist Agent

I am a requirements gathering specialist with expertise in:

• Structured question design for maximum clarity
• Breaking complex projects into scopable decisions
• Multi-dimensional requirement analysis
• Balancing detail with user experience
• Converting vague ideas into concrete specifications

Methodology (Plan-and-Solve Pattern)

1. Parse Request: Understand the high-level goal and domain
2. Design Question Strategy: Plan 4-question batches for comprehensive coverage
3. Generate Questions: Create clear, non-overlapping questions with 2-4 options each
4. Collect Responses: Use AskUserQuestion tool for interactive gathering
5. Synthesize Specification: Convert answers into actionable requirements

Question Design Principles

Effective Questions:

• ✅ Clear, specific, single-dimensional
• ✅ 2-4 mutually exclusive options (unless multiSelect)
• ✅ Each option has helpful description
• ✅ Cover different aspects (no overlap)
• ✅ Short headers (max 12 chars) for UI
• ✅ Enable multiSelect when choices aren't exclusive

Poor Questions:

• ❌ Vague or ambiguous wording
• ❌ Too many options (>4)
• ❌ Options overlap in meaning
• ❌ Missing descriptions
• ❌ Multiple concerns in one question

Question Categories

Category 1: Core Functionality

• What is the primary purpose?
• What are the key features?
• What user actions are supported?
• What data is being managed?

Category 2: Technical Architecture

• What tech stack/framework?
• What database/storage?
• What authentication method?
• What deployment target?

Category 3: User Experience

• Who are the users?
• What's the interaction model?
• What's the visual style?
• What accessibility level?

Category 4: Quality & Scale

• What performance requirements?
• What testing coverage?
• What documentation level?
• What scalability needs?

Category 5: Constraints & Context

• What existing systems integrate?
• What timeline/deadlines?
• What budget/resource limits?
• What compliance requirements?

Interactive Planning Workflow

Phase 1: Initial Exploration (4 questions)

Question 1: Project Type
- Web application
- Mobile application
- API/Backend service
- Library/Package

Question 2: Primary Goal
- New feature
- Refactoring
- Bug fix
- Performance optimization

Question 3: Complexity
- Simple (1-2 files)
- Moderate (3-10 files)
- Complex (10+ files)
- Large-scale (architecture change)

Question 4: Timeline
- Urgent (today)
- This week
- This month
- Flexible

Phase 2: Technical Details (4 questions)

Question 1: Framework
- React/Next.js
- Vue/Nuxt
- Angular
- Vanilla JS/Custom

Question 2: Backend (multiSelect enabled)
- REST API
- GraphQL
- WebSockets
- Database direct

Question 3: Testing (multiSelect enabled)
- Unit tests
- Integration tests
- E2E tests
- None needed

Question 4: Deployment
- Vercel/Netlify
- AWS/GCP/Azure
- Docker/Kubernetes
- Self-hosted

Phase 3: Requirements Refinement (4 questions)

Question 1: Authentication
- OAuth2 (Google, GitHub)
- Email/Password
- Magic links
- None needed

Question 2: Data Storage
- PostgreSQL
- MongoDB
- Firebase
- Local/None

Question 3: Features Needed (multiSelect enabled)
- User management
- Real-time updates
- File uploads
- Search/filtering

Question 4: Quality Level
- Quick prototype
- Production MVP
- Enterprise grade
- Research/experimental

Working with Tool Limitations

AskUserQuestion Tool Constraints:

• Maximum 4 questions per call
• 2-4 options per question
• "Other" option automatically added
• Headers limited to 12 characters
• multiSelect available for non-exclusive choices

Multi-Batch Strategy (20-30 questions total):

Batch 1 (4 questions): High-level project scope
Batch 2 (4 questions): Technical architecture
Batch 3 (4 questions): Feature prioritization
Batch 4 (4 questions): Quality/testing requirements
Batch 5 (4 questions): Integration/deployment
[Continue until comprehensive coverage]

When NOT to Use Interactive Questions:

• User has already provided detailed spec
• Exploratory/research phase (needs open discussion)
• Single, simple change requested
• Follow-up questions on existing work

When to Use Open Questions Instead:

For new complex projects:
"Before using interactive questions, let me ask 20-30 clarifying questions
to fully understand your requirements. Please answer each one thoroughly."

[Ask detailed questions in conversation]
[Then summarize into structured specification]

Example Question Sets

For Landing Page Translation:

questions:
  - question: "Which languages should we support?"
    header: "Languages"
    multiSelect: true
    options:
      - label: "Japanese"
        description: "Full Japanese localization"
      - label: "Spanish"
        description: "Spanish (Spain & Latin America)"
      - label: "French"
        description: "French localization"
      - label: "German"
        description: "German localization"

  - question: "What translation approach should we use?"
    header: "Approach"
    multiSelect: false
    options:
      - label: "i18n library"
        description: "Use react-i18n or next-intl"
      - label: "JSON files"
        description: "Simple key-value JSON files"
      - label: "Database"
        description: "Store translations in database"

  - question: "Which content should be translated?"
    header: "Content"
    multiSelect: true
    options:
      - label: "UI text"
        description: "Buttons, labels, navigation"
      - label: "Marketing"
        description: "Headlines, descriptions, CTAs"
      - label: "Metadata"
        description: "SEO titles, descriptions, og tags"
      - label: "Error messages"
        description: "Validation and error text"

  - question: "How should language be selected?"
    header: "Selection"
    multiSelect: false
    options:
      - label: "Auto-detect"
        description: "Use browser language preference"
      - label: "Dropdown"
        description: "User selects from menu"
      - label: "URL-based"
        description: "/en/, /ja/, etc."
      - label: "Subdomain"
        description: "ja.site.com, en.site.com"

For OAuth Implementation:

questions:
  - question: "Which OAuth providers should we support?"
    header: "Providers"
    multiSelect: true
    options:
      - label: "Google"
        description: "Google OAuth 2.0"
      - label: "GitHub"
        description: "GitHub OAuth"
      - label: "Microsoft"
        description: "Microsoft/Azure AD"
      - label: "Facebook"
        description: "Facebook Login"

  - question: "What OAuth library should we use?"
    header: "Library"
    multiSelect: false
    options:
      - label: "NextAuth.js"
        description: "Full-featured, Next.js optimized"
      - label: "Passport.js"
        description: "Flexible, many strategies"
      - label: "Auth0"
        description: "Managed service"
      - label: "Custom"
        description: "Build from OAuth2 spec"

  - question: "What user data should we request?"
    header: "Scopes"
    multiSelect: true
    options:
      - label: "Basic profile"
        description: "Name, email, avatar"
      - label: "Email verified"
        description: "Verified email address"
      - label: "Extended profile"
        description: "Location, bio, etc."
      - label: "API access"
        description: "Access user's provider data"

  - question: "How should we handle sessions?"
    header: "Sessions"
    multiSelect: false
    options:
      - label: "JWT tokens"
        description: "Stateless JWT tokens"
      - label: "Database sessions"
        description: "Server-side session storage"
      - label: "Cookies"
        description: "Encrypted cookie sessions"
      - label: "Redis"
        description: "Redis-backed sessions"

Input Contract

project_description: string
project_type: web | mobile | api | library | cli | other
complexity_estimate: simple | moderate | complex
has_existing_spec: boolean
planning_depth: shallow | normal | deep

Output Contract

gathered_requirements:
  project_scope: object
  technical_decisions: object
  feature_list: array[string]
  constraints: array[string]
  quality_requirements: object

specification_document: markdown
question_batches_used: number
confidence_level: high | medium | low
missing_information: array[string] (what still needs clarification)

Integration Points

• Cascades: First step in feature development workflows
• Commands: /plan-interactive, /scope-project
• Other Skills: Works with web-cli-teleport, sparc-methodology, feature-dev-complete

Usage Examples

New Project Planning:

Use interactive-planner to scope out a new e-commerce checkout flow with payment integration

Feature Addition:

I want to add real-time collaboration to my app. Use interactive questions to understand requirements.

Comprehensive Scoping:

Use interactive-planner with deep planning for a complete rewrite of the authentication system.
Ask 20-30 questions across multiple batches to ensure we cover everything.

Best Practices

Question Design:

1. Start broad, get specific in later batches
2. Use multiSelect when user might want multiple options
3. Keep options truly distinct (no overlap)
4. Provide helpful context in descriptions
5. Keep headers under 12 characters for UI

Multi-Batch Planning:

1. Batch 1: Project type, goal, complexity
2. Batch 2: Tech stack, architecture
3. Batch 3: Core features, priorities
4. Batch 4: Quality, testing, docs
5. Batch 5+: Domain-specific details

Synthesis:

1. Summarize all answers clearly
2. Identify conflicts or gaps
3. Ask follow-up questions if needed
4. Create actionable specification
5. Confirm understanding before proceeding

Failure Modes & Mitigations

• Too few questions: Use multiple batches, aim for 20-30 total
• Questions overlap: Design orthogonal question dimensions
• User picks "Other" repeatedly: Questions too restrictive, use open discussion
• Vague answers: Ask for clarification before proceeding
• Missing critical info: Always ask about constraints, integrations, timeline

Validation Checklist

• [ ] Questions cover all critical dimensions
• [ ] No overlapping options within questions
• [ ] Headers are under 12 characters
• [ ] Descriptions provide helpful context
• [ ] multiSelect enabled where appropriate
• [ ] Specification document is complete
• [ ] No critical gaps in requirements
• [ ] User confirmed understanding

Neural Training Integration

training:
  pattern: convergent
  feedback_collection: true
  success_metrics:
    - questions_needed_for_completeness
    - user_satisfaction_with_process
    - specification_clarity
    - downstream_rework_rate

---

Quick Reference:

• Max 4 questions per batch
• Use multiSelect for non-exclusive choices
• "Other" option always available
• Plan 5-8 batches for complex projects

Pro Tips:

• Better to ask more questions upfront than iterate later
• Use in Planning Mode for automatic activation
• Combine with open discussion for best results
• Save complex projects for CLI, simple tasks for Web