Add Clarification Phase to PLAN mode

[JeremyDev87]

Add Clarification Phase to PLAN Mode

Summary

This PR adds an optional Clarification Phase to PLAN MODE that enables AI to ask sequential questions to clarify ambiguous requirements before creating implementation plans. This feature significantly improves plan accuracy and reduces rework by ensuring all ambiguities are resolved upfront.

Problem Statement

Current Issues

Before this feature, PLAN MODE would immediately start creating plans even when requirements were ambiguous, leading to:

1. Ambiguous requirements incorporated into plans - AI would make arbitrary interpretations of unclear parts
2. Plans built on incorrect assumptions - Risk of proceeding in wrong direction
3. Increased rework costs - "This isn't what I meant" feedback during ACT phase requires starting over
4. Expectation mismatch - Final deliverables differ from user's original intent

Solution

Add an optional Clarification Phase that:

• Detects ambiguous requirements automatically
• Asks sequential, contextual questions to clarify uncertainties
• Uses multiple-choice format for easy user response
• Summarizes collected information before plan creation
• Can be skipped when requirements are already clear

Features

Core Functionality

• Automatic Ambiguity Detection - AI assesses requirements and triggers clarification when needed
• Sequential Q&A - One question at a time with progress indicator (Question N/M format)
• Multiple-Choice Questions - A/B/C options preferred for easy user response
• Progress Tracking - Visual progress indicator shows current question number
• Summary & Confirmation - Table summary of all collected information before plan creation
• Smart Skip - Automatically skips when requirements are already clear

Ambiguity Assessment

6-category checklist to determine if clarification is needed:

Category	Focus Areas
Scope	Feature boundary, affected modules, user roles
Priority	Core requirements vs optional features, MVP definition
Constraints	Technical limits, dependencies, compatibility, deadlines
Expected Behavior	Edge cases, error handling, default values
Non-functional	Performance, security, accessibility requirements
Integration	Existing code relations, data flow, API dependencies

Trigger Rule: If 2+ categories are unclear → Start Clarification Phase

Question Guidelines

• Question Count: 2-7 questions based on complexity
  • Simple feature: 2-3 questions
  • Standard feature: 3-5 questions
  • Complex feature: 5-7 questions
• Format: Multiple-choice with custom input option
• Language Support: Korean and English output formats
• Language Detection: Follows agent's communication.language setting, falls back to user input language

Changes

New Files

1. .ai-rules/rules/clarification-guide.md (138 lines)

   • Comprehensive guidelines for AI to generate contextual clarification questions
   • Ambiguity assessment checklist
   • Question format rules and examples
   • Korean/English output format templates
   • Special case handling guidelines

2. docs/plans/2025-12-22-plan-clarification-phase-design.md (271 lines)

   • Complete implementation design document
   • Problem definition and solution approach
   • Architecture diagram
   • Acceptance criteria
   • Out of scope items

Modified Files

1. .ai-rules/rules/core.md

   • Added "Clarification Phase (Optional)" section to PLAN mode
   • Integrated clarification phase into workflow
   • Added trigger conditions and phase rules
   • Documented question flow and skip conditions

2. .ai-rules/README.md

   • Updated PLAN mode description to mention Clarification Phase
   • Added Clarification Phase overview
   • Added reference to clarification-guide.md in "Further Reading"

3. .ai-rules/CHANGELOG.md

   • Added feature entry under "Added" section
   • Documented all key features and capabilities

Architecture

[User PLAN request]
       │
       v
[AI: Assess ambiguity level]
       │
   Ambiguous? ──No──> [Standard PLAN workflow]
       │
      Yes
       │
       v
[Start Clarification Phase]
       │
       v
[Question 1/N (multiple-choice)]
       │
       v
[User response]
       │
       v
    ... repeat ...
       │
       v
[All questions complete]
       │
       v
[Summary & Confirmation]
       │
       v
[Begin PLAN creation]

Implementation Approach

• Rule-based implementation - No MCP server changes needed
• AI-generated questions - Dynamic question generation based on context
• Context-based state - AI tracks progress in conversation, no server-side state
• Language-aware - Supports Korean and English with automatic detection

Usage Examples

Example 1: Ambiguous Request Triggers Clarification

User: "Add user authentication"

AI:

## Clarification Phase

### Question 1/4

**[Scope] clarification needed:**

Which authentication method should be implemented?

- **A)** Email/password only
- **B)** OAuth (Google, GitHub)
- **C)** Both email/password and OAuth

> Select your answer (A/B/C) or share your own input.

Example 2: Clear Request Skips Clarification

User: "Add email/password authentication with bcrypt hashing, JWT tokens, and session management. Include login, logout, and password reset endpoints."

AI: Skips Clarification Phase → Proceeds directly to PLAN creation

Benefits

1. Improved Plan Accuracy - Plans created only after all ambiguities resolved
2. Better User Engagement - Easy participation through multiple-choice questions
3. Reduced Rework - Clear requirements enable correct direction from start
4. Enhanced Communication - Systematic Q&A improves mutual understanding
5. Flexible - Can be skipped when requirements are already clear

Testing

• Clarification Phase triggers when ambiguous requirements detected
• Questions presented one at a time
• Progress indicator shows N/M format
• Multiple-choice format works correctly
• Summary table displayed after all questions
• User confirmation required before PLAN creation
• Phase skipped when requirements are clear
• Language detection works (Korean/English)
• Ambiguity assessment checklist implemented
• Question count guidelines followed (2-7 questions)

Related Issue

Closes #40

Files Changed

• .ai-rules/rules/clarification-guide.md - New (138 lines)
• .ai-rules/rules/core.md - Modified (+38 lines)
• .ai-rules/README.md - Modified (+10 lines)
• .ai-rules/CHANGELOG.md - Modified (+10 lines)
• docs/plans/2025-12-22-plan-clarification-phase-design.md - New (271 lines)

Statistics

• 5 files changed
• 466 insertions, 1 deletion
• 2 new files added
• 3 files updated

Documentation

• Guidelines: .ai-rules/rules/clarification-guide.md
• Design Document: docs/plans/2025-12-22-plan-clarification-phase-design.md
• Integration: .ai-rules/rules/core.md

Out of Scope

The following are explicitly out of scope for this PR:

• Clarification for ACT MODE and EVAL MODE (PLAN only)
• Multilingual question templates beyond Korean/English
• Question history persistence
• Learning from past clarifications

Next Steps

• Test with real-world ambiguous PLAN requests
• Gather user feedback on question quality
• Monitor usage patterns and adjust guidelines as needed
• Consider extending to ACT/EVAL modes if successful

Notes

This feature significantly improves the PLAN mode workflow by ensuring requirements are clarified before plan creation. The rule-based approach means no infrastructure changes are needed - AI assistants simply follow the documented guidelines to implement the clarification phase.

The implementation is designed to be:

• Non-intrusive - Only triggers when needed
• User-friendly - Multiple-choice format makes responses easy
• Flexible - Can be skipped or customized per user preference
• Extensible - Easy to add more question categories or formats in the future