clavix 4.2.0 → 4.3.1

package/dist/templates/instructions/troubleshooting 2/jumped-to-implementation.md

@@ -1,234 +0,0 @@
-# Troubleshooting: Agent Jumped to Implementation
-
-## Problem Description
-
-Agent started implementing the feature instead of staying in requirements/planning mode during Clavix workflows.
-
----
-
-## Symptoms
-
-- Agent generated application code during `/clavix:start` conversational mode
-- Agent created functions, components, or classes for the feature being discussed
-- Agent built implementation examples instead of asking clarifying questions
-- Agent jumped from requirements gathering to coding without explicit user request
-
----
-
-## Why This Happens
-
-**Root causes:**
-
-1. **Missing CLAVIX MODE boundary** - Agent didn't see or internalize the "DO NOT IMPLEMENT" instruction
-2. **Default helpfulness** - Agents are trained to be helpful, which often means "solve the problem" = implement
-3. **Implicit mode boundaries** - "Stay in conversational mode" is too subtle without explicit gates
-4. **Premature optimization** - Agent thinks "I have enough info to implement" after 1-2 questions
-
----
-
-## Immediate Fix
-
-If an agent has already jumped to implementation:
-
-### Step 1: Stop Implementation
-
-Agent should:
-1. **STOP** writing implementation code immediately
-2. **Delete** or discard the implementation attempt
-3. **Acknowledge** the mistake
-
-### Step 2: Apologize and Correct
-
-Agent should output:
-
-```markdown
-I apologize - I was jumping to implementation prematurely.
-
-I'm in Clavix mode, which is for requirements gathering and planning, NOT for implementing features yet.
-
-Let me return to asking clarifying questions about your requirements instead.
-```
-
-### Step 3: Return to Correct Mode
-
-Agent should:
-1. **Return** to asking clarifying questions (if in `/clavix:start`)
-2. **Return** to extracting requirements (if in `/clavix:summarize`)
-3. **Return** to analyzing prompts (if in `/clavix:fast` or `/clavix:deep`)
-4. **Return** to generating PRD (if in `/clavix:prd`)
-
-**NOT** continue with implementation.
-
----
-
-## Prevention Strategies
-
-### For Template Authors
-
-**1. Add CLAVIX MODE Block at Top**
-
-Every workflow template should start with:
-
-```markdown
-## CLAVIX MODE: Requirements & Planning Only
-
-**You are in Clavix prompt/PRD development mode. You help create planning documents, NOT implement features.**
-
-**YOUR ROLE:**
-- ✓ [What you should do]
-
-**DO NOT IMPLEMENT. DO NOT IMPLEMENT. DO NOT IMPLEMENT.**
-- ✗ DO NOT write application code
-- ✗ DO NOT implement the feature being discussed
-- ✗ DO NOT generate component/function implementations
-
-**ONLY implement if user explicitly says: "Now implement this"**
-```
-
-**2. Repeat Mode Boundaries**
-
-Don't rely on seeing it once. Repeat critical boundaries:
-- At workflow start
-- Before agent might implement (e.g., after questions in conversational mode)
-- In troubleshooting sections
-- At least 3 times in different locations
-
-**3. Add Self-Correction Triggers**
-
-Include explicit checks:
-
-```markdown
-**Self-Check: Am I Implementing?**
-
-If you catch yourself writing application code, STOP IMMEDIATELY.
-1. Delete the implementation
-2. Apologize
-3. Return to requirements mode
-```
-
-**4. Use Explicit Imperative Language**
-
-✓ "DO NOT write code"
-✓ "DO NOT implement features"
-✓ "Your role is requirements gathering, NOT execution"
-
-✗ "Stay in conversational mode" (too subtle)
-✗ "You are gathering requirements" (descriptive, not imperative)
-
----
-
-### For Users
-
-**1. Set Clear Expectations Upfront**
-
-When starting a Clavix workflow, remind the agent:
-
-```markdown
-/clavix:start
-
-Remember: We're just gathering requirements and planning. Don't implement anything yet - I'll ask you to build it later once we have a solid plan.
-```
-
-**2. Catch Early and Redirect**
-
-If agent starts implementing:
-
-```markdown
-Hold on - I don't want implementation yet. I just want to plan and document requirements first.
-
-Let's stay in planning mode. Ask me more questions about what I need.
-```
-
-**3. Explicit Implementation Request**
-
-When you DO want implementation:
-
-```markdown
-Great PRD! Now implement this feature based on the PRD we created.
-```
-
-Be explicit. "Now implement" or "Build this" makes it clear.
-
----
-
-## Testing for This Issue
-
-### Test Scenario 1: Conversational Mode
-
-**Setup:**
-```markdown
-User: /clavix:start
-User: I want to build a todo app with authentication
-```
-
-**Expected behavior:**
-- Agent asks clarifying questions
-- Agent does NOT generate code
-- Agent stays in requirements gathering mode
-
-**Failure indicator:**
-- Agent generates TodoApp component or authentication code
-
----
-
-### Test Scenario 2: After Few Questions
-
-**Setup:**
-```markdown
-User: /clavix:start
-User: I want real-time notifications in my app
-Agent: [Asks 2-3 questions]
-User: [Answers questions]
-```
-
-**Expected behavior:**
-- Agent asks more questions to deepen understanding
-- Agent does NOT implement WebSockets or notification system
-
-**Failure indicator:**
-- Agent generates implementation after thinking "I have enough info"
-
----
-
-## Related Issues
-
-- **Mode Confusion**: See `mode-confusion.md` if agent is unclear which mode is active
-- **Premature Completion**: Agent finishing workflows too early
-- **Missing Checkpoints**: Agent skipping validation steps
-
----
-
-## Success Indicators
-
-Agent is working correctly when:
-- ✓ Agent asks 5+ clarifying questions before considering summarization
-- ✓ Agent never generates application code during Clavix workflows (unless explicitly requested)
-- ✓ Agent explicitly states "I'm in planning mode" or similar acknowledgment
-- ✓ Agent suggests `/clavix:summarize` instead of jumping to implementation
-- ✓ Agent asks "Should I implement or continue planning?" when uncertain
-
----
-
-## Quick Reference
-
-**If agent implements during Clavix workflow:**
-
-1. **Stop** - Agent stops generating code
-2. **Apologize** - "I apologize, I was jumping to implementation..."
-3. **Return** - Go back to requirements/planning mode
-4. **Reference** - Point to CLAVIX MODE boundary in instructions
-
-**Prevention checklist:**
-- ✓ CLAVIX MODE block at top of workflow
-- ✓ "DO NOT IMPLEMENT" repeated 3+ times
-- ✓ Self-correction triggers included
-- ✓ Explicit user request required for implementation
-- ✓ Mode boundaries use imperative language
-
----
-
-## See Also
-
-- `.clavix/instructions/core/clavix-mode.md` - Complete mode boundary explanation
-- `.clavix/instructions/workflows/start.md` - Conversational mode workflow
-- `.clavix/instructions/troubleshooting/mode-confusion.md` - When agent is unclear about mode

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