docs(05): capture phase context

Phase 05: conversation-engine
- Implementation decisions documented
- Phase boundary established
This commit is contained in:
Mai Development
2026-01-28 23:57:30 -05:00
parent 25bd28454d
commit 6e7def8860

View File

@@ -1,6 +1,6 @@
# Phase 5: Conversation Engine - Context # Phase 5: Conversation Engine - Context
**Gathered:** 2026-01-28 **Gathered:** 2026-01-29
**Status:** Ready for planning **Status:** Ready for planning
<domain> <domain>
@@ -14,37 +14,33 @@ Build Mai's conversational intelligence - how she handles multi-turn conversatio
## Implementation Decisions ## Implementation Decisions
### Conversation flow patterns ### Conversation flow patterns
- Break down complex requests and confirm each part before proceeding - Handle complex requests in one comprehensive response (rather than breaking down)
- Always reference specific previous exchanges for follow-up questions - Use conversational references ("earlier you mentioned...") for follow-up questions
- Ask for clarification when requests are ambiguous (don't make assumptions) - Ask for clarification when requests are ambiguous (don't make assumptions)
- Track state and reference previous steps in multi-step conversations - Track state and reference previous steps in multi-step conversations
- Handle topic changes naturally without explicit acknowledgment
- Wait for users to finish incomplete thoughts before responding
- Use user's level of terminology for technical discussions
- Offer to start over when user seems frustrated or confused
### Thinking transparency ### Thinking transparency
- Offer thinking on demand (explain reasoning when users ask "how did you decide?") - Keep reasoning hidden by default (not show internal thinking process)
- Explain limitations only when relevant to the current answer - Explain limitations only when relevant to the current answer
- Be confident unless specifically unsure about an answer - Be confident unless specifically unsure about an answer
- Explain why asking questions only when the request is unusual - Keep clarification questions concise without extensive explanation
### Response timing and pacing ### Response timing and pacing
- Use variable timing based on context rather than fixed response times - Use consistent timing always (similar response time regardless of complexity)
- Use natural conversation flow for thinking indicators (no explicit "thinking..." messages) - Use natural conversation flow for thinking indicators (no explicit "thinking..." messages)
- Stream long, complex responses as they're generated in real-time - Stream long, complex responses as they're generated in real-time
- Offer pacing preference for multi-step processes (step-by-step vs continuous) - Offer pacing preference for multi-step processes (step-by-step vs continuous)
### Clarification handling ### Clarification handling
- Proactively analyze user input to detect ambiguity and unclear requests - Use pattern-based detection to identify ambiguity (common patterns of unclear requests)
- Phrase clarification questions gently and conversationally - Phrase clarification questions gently and conversationally
- Work with available information when users provide insufficient data (note assumptions) - Work with available information when users provide insufficient data (note assumptions)
- Ask users which information is correct when detecting conflicting input - Choose most recent information when detecting conflicting input
### Claude's Discretion ### Claude's Discretion
- Exact timing algorithms for response generation - Exact patterns for ambiguity detection
- Specific wording for clarification questions - Specific wording for clarification questions
- Thresholds for detecting ambiguity vs confidence - Timing algorithms for response generation
- Progress indicator designs for long processes - Progress indicator designs for long processes
</decisions> </decisions>
@@ -53,8 +49,8 @@ Build Mai's conversational intelligence - how she handles multi-turn conversatio
## Specific Ideas ## Specific Ideas
- "I want Mai to feel like a thoughtful conversation partner, not just a Q&A machine" - "I want Mai to feel like a thoughtful conversation partner, not just a Q&A machine"
- "When users are frustrated, offering a fresh start is better than trying to fix the current approach" - "Consistent timing helps users know what to expect from Mai"
- "Complex requests should feel collaborative - Mai breaks them down and gets buy-in on each part" - "Complex requests should feel comprehensive - Mai handles everything at once"
- "Natural conversation flow means responses should feel like someone is actually thinking, not just processing" - "Natural conversation flow means responses should feel like someone is actually thinking, not just processing"
</specifics> </specifics>
@@ -62,14 +58,11 @@ Build Mai's conversational intelligence - how she handles multi-turn conversatio
<deferred> <deferred>
## Deferred Ideas ## Deferred Ideas
- Voice interaction patterns - separate phase for voice interface None — discussion stayed within phase scope
- Emotional intelligence and mood detection - future enhancement
- Multi-language conversation handling - later phase
- Conversation analytics and insights - separate phase
</deferred> </deferred>
--- ---
*Phase: 05-conversation-engine* *Phase: 05-conversation-engine*
*Context gathered: 2026-01-28* *Context gathered: 2026-01-29*