clavix 4.2.0 → 4.3.2

package/dist/templates/instructions/troubleshooting 2/mode-confusion.md

@@ -1,402 +0,0 @@
-# Troubleshooting: Mode Confusion
-
-## Problem Description
-
-Agent is unclear whether they should be in planning mode (gathering requirements, creating PRDs) or implementation mode (writing code, building features).
-
----
-
-## Symptoms
-
-- Agent asks "Should I implement this or just plan it?"
-- Agent alternates between asking questions and generating code
-- Agent generates partial implementation then stops uncertainly
-- User and agent have misaligned expectations about what's happening
-- Agent starts multiple times with different approaches
-
----
-
-## Why This Happens
-
-**Root causes:**
-
-1. **Ambiguous user request** - User says "build X" which could mean "plan to build X" or "implement X now"
-2. **Missing CLAVIX MODE context** - Agent didn't see mode boundary instructions
-3. **Implicit mode transitions** - No clear signal when switching between planning and implementation
-4. **Conversation drift** - Started in planning mode but gradually shifted toward implementation
-5. **Tool ambiguity** - Clavix commands not clearly distinguished from normal conversation
-
----
-
-## Immediate Fix
-
-If mode is unclear:
-
-### Step 1: Agent Should Ask Explicitly
-
-When uncertain, agent should ALWAYS ask:
-
-```markdown
-Just to clarify - which mode should I be in?
-
-**Option 1: Planning Mode (Clavix)**
-- Gather requirements and create planning documents
-- Generate PRDs and optimized prompts
-- Ask clarifying questions
-- **No implementation yet**
-
-**Option 2: Implementation Mode**
-- Write actual code
-- Build the feature
-- Create components/functions
-- **Start implementing now**
-
-Which would you like me to do?
-```
-
----
-
-### Step 2: User Should Clarify
-
-User should explicitly state:
-
-**For planning:**
-```markdown
-Just planning for now. Help me create a solid PRD first.
-```
-
-**For implementation:**
-```markdown
-Let's implement this now. Build the feature based on what we've discussed.
-```
-
----
-
-### Step 3: Agent Confirms Mode
-
-Agent should acknowledge:
-
-**Planning mode:**
-```markdown
-Got it - I'm in planning mode. I'll gather requirements and create documentation, but won't implement yet.
-
-Let's start with some clarifying questions...
-```
-
-**Implementation mode:**
-```markdown
-Understood - I'll implement this now based on our requirements.
-
-Let me start building...
-```
-
----
-
-## Prevention Strategies
-
-### For Template Authors
-
-**1. Clear Mode Declaration**
-
-Every workflow should declare its mode upfront:
-
-```markdown
-## CLAVIX MODE: Requirements & Planning Only
-
-You are in PLANNING mode. Do NOT implement.
-```
-
-Or for implementation:
-
-```markdown
-## IMPLEMENTATION MODE
-
-You are now in implementation mode. Write code based on requirements.
-```
-
----
-
-**2. Mode Transition Markers**
-
-When transitioning between modes, make it explicit:
-
-```markdown
-**TRANSITION:** Entering planning mode
-**TRANSITION:** Exiting planning mode, starting implementation
-```
-
----
-
-**3. Decision Points Have Clarification Prompts**
-
-When agent might be uncertain:
-
-```markdown
-**If uncertain whether to implement:**
-Ask user: "Should I implement this now, or continue planning?"
-```
-
----
-
-### For Users
-
-**1. Use Explicit Commands**
-
-**For planning:**
-- `/clavix:start` - Start conversational planning
-- `/clavix:prd` - Generate PRD
-- `/clavix:summarize` - Extract requirements
-
-**For implementation:**
-- "Now implement this"
-- "Build the feature"
-- "Start coding"
-
----
-
-**2. Set Expectations Early**
-
-At conversation start:
-
-```markdown
-Let's plan this out first before implementing. I want a solid PRD.
-```
-
-Or:
-
-```markdown
-I already have requirements. Let's jump straight to implementation.
-```
-
----
-
-**3. Clarify When Confused**
-
-If agent seems confused:
-
-```markdown
-To be clear: we're just planning right now. Don't implement yet.
-```
-
----
-
-## Common Confusion Scenarios
-
-### Scenario 1: Ambiguous "Build" Request
-
-**User says:** "Help me build an authentication system"
-
-**Agent thinks:**
-- Option A: Help plan how to build it (planning mode)
-- Option B: Implement it now (implementation mode)
-
-**Solution:**
-
-Agent asks:
-```markdown
-When you say "build an authentication system," do you want me to:
-
-1. **Help plan it**: Gather requirements, create a PRD, document what needs to be built
-2. **Implement it now**: Write the actual authentication code and components
-
-Which would you prefer?
-```
-
----
-
-### Scenario 2: Mid-Conversation Shift
-
-**Starts in planning:**
-```markdown
-User: /clavix:start
-User: I want a dashboard
-Agent: [Asks questions about dashboard]
-User: [Answers 5 questions]
-User: Looks good, let's do it!
-```
-
-**Agent thinks:** "Do it" = implement? Or "looks good" = continue planning?
-
-**Solution:**
-
-Agent asks:
-```markdown
-When you say "let's do it," do you mean:
-
-1. Continue planning and create a PRD/summary?
-2. Start implementing the dashboard now?
-```
-
----
-
-### Scenario 3: PRD Then Implementation
-
-**Flow:**
-```markdown
-User: /clavix:prd
-Agent: [Creates PRD]
-User: Perfect! Now make it happen.
-```
-
-**Agent thinks:** "Make it happen" = implement? Or generate more docs?
-
-**Solution:**
-
-Agent interprets:
-```markdown
-**TRANSITION:** You've approved the PRD. I understand you want implementation now.
-
-I'll build the features described in the PRD. Starting with [first feature]...
-```
-
-But if uncertain:
-```markdown
-By "make it happen," do you mean:
-1. Implement the features in the PRD now?
-2. Create additional planning documents?
-```
-
----
-
-## Decision Tree for Agents
-
-```
-User request received
-    │
-    ├─ Is Clavix command? (/clavix:*) ────► Planning Mode
-    │
-    ├─ User said "implement" / "build now" / "create code"? ────► Implementation Mode
-    │
-    ├─ User said "plan" / "PRD" / "requirements"? ────► Planning Mode
-    │
-    ├─ User said "help me build..."? ────► ASK FOR CLARIFICATION
-    │
-    ├─ Currently in /clavix:* workflow? ────► Stay in Planning Mode
-    │
-    ├─ User approved PRD and said "do it"? ────► Likely Implementation Mode (confirm if uncertain)
-    │
-    └─ Unclear? ────► ASK: "Should I plan or implement?"
-```
-
----
-
-## Mode Indicators
-
-### Clear Planning Indicators
-
-- `/clavix:start`
-- `/clavix:prd`
-- `/clavix:summarize`
-- "Let's plan this"
-- "Help me create a PRD"
-- "I want to document requirements"
-- "What should I build?"
-
----
-
-### Clear Implementation Indicators
-
-- "Now implement this"
-- "Build the feature"
-- "Write the code"
-- "Create the component"
-- "Let's start coding"
-- "Make it work"
-- User has approved PRD + says "go ahead"
-
----
-
-### Ambiguous Phrases (ASK FOR CLARIFICATION)
-
-- "Help me build X" ← Could be plan OR implement
-- "Let's do X" ← Could be plan OR implement
-- "Create an X" ← Could be PRD OR implementation
-- "I need an X" ← Could be plan OR implement
-- "Make it happen" ← Could be continue planning OR start implementing
-
-**When hearing ambiguous phrase → Agent asks for clarification**
-
----
-
-## Testing for Mode Confusion
-
-### Test: Ambiguous Request Handling
-
-**Input:**
-```markdown
-User: Help me build a todo app
-```
-
-**Expected behavior:**
-- Agent asks: "Should I help plan it, or implement it now?"
-- Agent does NOT assume one or the other
-
-**Failure indicator:**
-- Agent immediately starts planning without asking
-- Agent immediately starts implementing without asking
-
----
-
-### Test: Mid-Workflow Ambiguity
-
-**Input:**
-```markdown
-User: /clavix:start
-[Conversation about requirements]
-User: Sounds great, let's go!
-```
-
-**Expected behavior:**
-- Agent asks: "Should I summarize our requirements, or start implementing?"
-- Agent does NOT assume "let's go" means implement
-
----
-
-## Success Indicators
-
-Mode clarity is working when:
-- ✓ Agent knows whether to plan or implement
-- ✓ Agent asks when uncertain instead of guessing
-- ✓ User and agent expectations are aligned
-- ✓ No confusion about what's being produced (PRD vs code)
-- ✓ Clear transitions between modes when they occur
-
----
-
-## Quick Reference
-
-**Agent is confused?**
-
-Agent should ask:
-```markdown
-Should I:
-1. Plan and document (create PRDs, gather requirements)?
-2. Implement (write code and build features)?
-```
-
-**User wants to clarify?**
-
-User should say:
-```markdown
-Planning mode: "Just create a PRD / gather requirements for now"
-Implementation mode: "Implement this now / start coding"
-```
-
-**Template authors preventing confusion?**
-
-Add to templates:
-```markdown
-## CLAVIX MODE: Requirements & Planning Only
-
-[Clear mode boundary]
-
-**If uncertain whether to implement, ASK the user.**
-```
-
----
-
-## See Also
-
-- `.clavix/instructions/core/clavix-mode.md` - Complete mode boundary explanation
-- `.clavix/instructions/troubleshooting/jumped-to-implementation.md` - Agent implementing prematurely
-- `.clavix/instructions/workflows/start.md` - Conversational mode workflow