clavix 4.2.0 → 4.3.2

package/dist/templates/instructions/troubleshooting 2/skipped-file-creation.md

@@ -1,385 +0,0 @@
-# Troubleshooting: Agent Skipped File Creation
-
-## Problem Description
-
-Agent completed a Clavix workflow but didn't create the expected output files. Content was displayed in chat but not saved to disk.
-
----
-
-## Symptoms
-
-- Agent says "files created" but they don't exist in `.clavix/outputs/`
-- Agent provides content in chat instead of using Write tool
-- Agent completes `/clavix:summarize` but no mini-prd.md, original-prompt.md, or optimized-prompt.md files
-- Agent finishes `/clavix:fast` or `/clavix:deep` but no saved prompt file
-- Agent generates PRD content but no PRD.md or PRD-quick.md files
-
----
-
-## Why This Happens
-
-**Root causes:**
-
-1. **Suggestive language** - Instructions say "suggest saving" instead of "you MUST save"
-2. **Missing Write tool instructions** - No explicit "Use the Write tool to create..." steps
-3. **Optional phrasing** - "If filesystem access available" makes file creation optional
-4. **No verification step** - Agent can't detect that files weren't created
-5. **Wrong instruction ordering** - File creation buried at step 5 or 6 instead of step 3
-6. **Agent assumes limited access** - Some agents think they can't write files
-
----
-
-## Immediate Fix
-
-If files weren't created:
-
-### Step 1: Verify Files Don't Exist
-
-Check the expected location:
-
-```bash
-ls -la .clavix/outputs/[project-name]/
-```
-
-If directory or files missing, proceed with fix.
-
----
-
-### Step 2: Request Explicit File Creation
-
-Tell the agent:
-
-```markdown
-The files weren't created. Please create them now using these exact steps:
-
-**Step 1: Create directory**
-```bash
-mkdir -p .clavix/outputs/[project-name]
-```
-
-**Step 2: Write mini-prd.md**
-Use the Write tool to create `.clavix/outputs/[project-name]/mini-prd.md` with the content you showed me earlier.
-
-**Step 3: Write original-prompt.md**
-Use the Write tool to create `.clavix/outputs/[project-name]/original-prompt.md`
-
-**Step 4: Write optimized-prompt.md**
-Use the Write tool to create `.clavix/outputs/[project-name]/optimized-prompt.md`
-
-**Step 5: Confirm files exist**
-List the created files so I can verify.
-```
-
----
-
-### Step 3: Verify Creation
-
-After agent claims files are created, verify:
-
-```bash
-ls -la .clavix/outputs/[project-name]/
-cat .clavix/outputs/[project-name]/mini-prd.md
-```
-
-Files should exist and contain the expected content.
-
----
-
-## Prevention Strategies
-
-### For Template Authors
-
-**1. Use Proven File Creation Pattern**
-
-Copy the explicit pattern from `fast.md` or `.clavix/instructions/core/file-operations.md`:
-
-```markdown
-**CREATE OUTPUT FILES (REQUIRED)**
-
-You MUST create [N] files. This is not optional.
-
-**Step 1: Create directory structure**
-```bash
-mkdir -p .clavix/outputs/[project-name]
-```
-
-**Step 2: Write [filename]**
-Use the Write tool to create `.clavix/outputs/[project-name]/[filename]`
-
-Content:
-[Template or exact content]
-
-**Step 3: Write [another-filename]**
-Use the Write tool to create `.clavix/outputs/[project-name]/[another-filename]`
-
-**Step N: Verify files exist**
-List created files:
-```
-✓ .clavix/outputs/[project-name]/file1.md
-✓ .clavix/outputs/[project-name]/file2.md
-```
-
-**CHECKPOINT:** All files created successfully
-```
-
-**2. Use Imperative Language**
-
-✓ "You MUST create files"
-✓ "Use the Write tool to..."
-✓ "This is REQUIRED"
-✓ "Create [specific file] now"
-
-✗ "Suggest saving to..."
-✗ "If filesystem access available..."
-✗ "You could save..."
-✗ "Consider creating..."
-
----
-
-**3. Name the Tool Explicitly**
-
-✓ "Use the Write tool to create..."
-✓ "Call the Write tool with..."
-
-✗ "Save to..." (vague - how?)
-✗ "Create..." (vague - with what tool?)
-✗ "Output to..." (unclear method)
-
----
-
-**4. Add Verification Step**
-
-Always include a step to verify files exist:
-
-```markdown
-**Step N: Verify File Creation**
-
-List the created files to confirm they exist:
-```
-✓ file1.md
-✓ file2.md
-✓ file3.md
-```
-
-If any file is missing, something went wrong. Review and retry file creation steps.
-```
-
----
-
-**5. Correct Step Ordering**
-
-File creation should be step 3 or 4, NOT step 5 or 6.
-
-**Good order:**
-1. Validate requirements
-2. Extract/analyze
-3. **CREATE FILES** ← Early in process
-4. Apply optimizations
-5. Highlight insights
-6. Present summary
-
-**Bad order:**
-1. Validate requirements
-2. Extract/analyze
-3. Apply optimizations
-4. Highlight insights
-5. **Suggest saving** ← Too late, often skipped
-6. Present summary
-
----
-
-**6. Make File Creation Non-Optional**
-
-Remove any language that makes it optional:
-
-✗ "If filesystem access available..."
-✗ "Try to save..."
-✗ "Optionally create..."
-✗ "You can save..."
-
-✓ "You MUST create..."
-✓ "This step is REQUIRED"
-✓ "Create these files (not optional)"
-
----
-
-### For Platform-Specific Adaptations
-
-Some platforms have limited file access. Add fallback:
-
-```markdown
-**Step 2: Write file (with fallback)**
-
-**Primary:** Use the Write tool to create `.clavix/outputs/[project]/file.md`
-
-**Fallback (if Write tool unavailable):**
-If file creation fails, display content and instruct user:
-
-⚠️ File creation unavailable. Please save this manually:
-
-**Path:** `.clavix/outputs/[project]/file.md`
-
-**Content:**
-```
-[Content here]
-```
-
-Copy the content above and save to the specified path.
-```
-
----
-
-## Testing for This Issue
-
-### Test Scenario 1: Summarization Workflow
-
-**Setup:**
-```markdown
-User: /clavix:start
-[Conversation happens]
-User: /clavix:summarize
-```
-
-**Expected behavior:**
-- Agent creates .clavix/outputs/[project]/ directory
-- Agent writes mini-prd.md
-- Agent writes original-prompt.md
-- Agent writes optimized-prompt.md
-- Agent lists files to verify
-- **CHECKPOINT:** All files created successfully
-
-**Test:**
-```bash
-ls -la .clavix/outputs/[project]/
-```
-
-Should show all three files.
-
-**Failure indicator:**
-- Directory doesn't exist
-- Files missing
-- Agent showed content in chat but didn't write files
-
----
-
-### Test Scenario 2: Fast Improvement
-
-**Setup:**
-```markdown
-User: /clavix:fast [prompt]
-```
-
-**Expected behavior:**
-- Agent analyzes prompt
-- Agent generates optimized version
-- Agent creates .clavix/outputs/prompts/fast/ directory
-- Agent writes fast-YYYYMMDD-HHMM.md file
-- Agent verifies file created
-
-**Test:**
-```bash
-ls -la .clavix/outputs/prompts/fast/
-```
-
-Should show saved prompt file.
-
----
-
-## Common Patterns That Fail
-
-### ❌ Pattern 1: Vague Suggestion
-
-```markdown
-5. Suggest saving to `.clavix/outputs/[project]/`
-```
-
-**Why it fails:** "Suggest" is passive, no Write tool instruction, no steps.
-
----
-
-### ❌ Pattern 2: Optional Language
-
-```markdown
-4. Save to `.clavix/outputs/` if filesystem access available
-```
-
-**Why it fails:** "If available" makes it optional. Agent skips if uncertain.
-
----
-
-### ❌ Pattern 3: No Tool Specified
-
-```markdown
-3. Save the following files:
-   - mini-prd.md
-   - optimized-prompt.md
-```
-
-**Why it fails:** Doesn't say HOW to save. No Write tool instruction.
-
----
-
-### ❌ Pattern 4: No Verification
-
-```markdown
-3. Use Write tool to create files in .clavix/outputs/
-4. Display summary
-```
-
-**Why it fails:** No verification step. Can't detect if files weren't created.
-
----
-
-## Working Patterns
-
-### ✅ Pattern: Explicit Numbered Steps
-
-```markdown
-**CREATE FILES (REQUIRED)**
-
-**Step 1:** Create directory
-```bash
-mkdir -p .clavix/outputs/project
-```
-
-**Step 2:** Use Write tool to create file1.md
-**Step 3:** Use Write tool to create file2.md
-**Step 4:** Verify all files exist
-**CHECKPOINT:** Files created successfully
-```
-
-**Why it works:** Imperative, explicit tool, verification, checkpoint.
-
----
-
-## Quick Diagnosis
-
-**Agent says files created but they don't exist?**
-
-Check template for:
-- ✗ "Suggest saving" language?
-- ✗ "If available" conditional?
-- ✗ No Write tool instruction?
-- ✗ No verification step?
-- ✗ File creation at step 5+?
-
-**Fix:** Replace with proven pattern from `.clavix/instructions/core/file-operations.md`
-
----
-
-## Success Indicators
-
-File creation is working when:
-- ✓ Files physically exist in .clavix/outputs/
-- ✓ Files contain expected content structure
-- ✓ Agent displays verification message with file paths
-- ✓ Checkpoint marker confirms file creation
-- ✓ User can open and read the files
-
----
-
-## See Also
-
-- `.clavix/instructions/core/file-operations.md` - Complete file creation patterns
-- `.clavix/instructions/workflows/summarize.md` - Corrected summarization with file creation
-- `.clavix/instructions/core/verification.md` - Verification patterns