clavix 2.1.2 → 2.3.0

package/README.md

@@ -1,5 +1,5 @@
 # Clavix
-> AI prompt improvement & PRD generation CLI (CLEAR Framework)
+> Transform vague ideas into production-ready prompts. Analyze gaps, generate PRDs, and supercharge your AI coding workflow with the CLEAR framework.
 
 ## Table of contents
 - [Why Clavix?](#why-clavix)
@@ -19,8 +19,8 @@ Clavix is built on CLEAR (Concise, Logical, Explicit, Adaptive, Reflective), an
 | Category | Providers |
 | --- | --- |
 | IDE & editor extensions | Cursor · Windsurf · Kilocode · Roocode · Cline |
-| CLI agents | Claude Code · Droid CLI · CodeBuddy CLI · OpenCode · Gemini CLI · Qwen Code · Amp · Crush CLI · Codex CLI |
-| Universal adapters | AGENTS.md · OCTO.md · WARP.md |
+| CLI agents | Claude Code · Droid CLI · CodeBuddy CLI · OpenCode · Gemini CLI · Qwen Code · Amp · Crush CLI · Codex CLI · Augment CLI |
+| Universal adapters | AGENTS.md · GitHub Copilot · OCTO.md · WARP.md |
 
 Provider paths and argument placeholders are listed in [docs/providers.md](docs/providers.md).
 

package/dist/cli/commands/init.js

@@ -46,6 +46,7 @@ const doc_injector_1 = require("../../core/doc-injector");
 const agents_md_generator_1 = require("../../core/adapters/agents-md-generator");
 const octo_md_generator_1 = require("../../core/adapters/octo-md-generator");
 const warp_md_generator_1 = require("../../core/adapters/warp-md-generator");
+const copilot_instructions_generator_1 = require("../../core/adapters/copilot-instructions-generator");
 const file_system_1 = require("../../utils/file-system");
 const config_1 = require("../../types/config");
 const gemini_adapter_1 = require("../../core/adapters/gemini-adapter");
@@ -98,10 +99,6 @@ class Init extends core_1.Command {
                             name: 'CodeBuddy (.codebuddy/commands/)',
                             value: 'codebuddy',
                         },
-                        {
-                            name: 'Copilot CLI (.github/agents/)',
-                            value: 'copilot',
-                        },
                         {
                             name: 'Crush CLI (.crush/commands/clavix/)',
                             value: 'crush',
@@ -154,6 +151,10 @@ class Init extends core_1.Command {
                             name: 'agents.md (Universal - for tools without slash commands)',
                             value: 'agents-md',
                         },
+                        {
+                            name: 'GitHub Copilot (.github/copilot-instructions.md)',
+                            value: 'copilot-instructions',
+                        },
                         {
                             name: 'Warp (WARP.md - optimized for Warp)',
                             value: 'warp-md',
@@ -193,6 +194,12 @@ class Init extends core_1.Command {
                     await agents_md_generator_1.AgentsMdGenerator.generate();
                     continue;
                 }
+                // Handle copilot-instructions separately (it's not an adapter)
+                if (providerName === 'copilot-instructions') {
+                    console.log(chalk_1.default.gray('  ✓ Generating .github/copilot-instructions.md...'));
+                    await copilot_instructions_generator_1.CopilotInstructionsGenerator.generate();
+                    continue;
+                }
                 // Handle octo-md separately (it's not an adapter)
                 if (providerName === 'octo-md') {
                     console.log(chalk_1.default.gray('  ✓ Generating OCTO.md...'));

package/dist/core/adapters/copilot-instructions-generator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generator for GitHub Copilot instructions file
+ * Provides workflow instructions via .github/copilot-instructions.md
+ */
+export declare class CopilotInstructionsGenerator {
+    static readonly TARGET_FILE = ".github/copilot-instructions.md";
+    static readonly START_MARKER = "<!-- CLAVIX:START -->";
+    static readonly END_MARKER = "<!-- CLAVIX:END -->";
+    /**
+     * Generate or update .github/copilot-instructions.md with Clavix workflows
+     */
+    static generate(): Promise<void>;
+    /**
+     * Inject or update managed block in .github/copilot-instructions.md
+     */
+    private static injectManagedBlock;
+    /**
+     * Escape special regex characters
+     */
+    private static escapeRegex;
+    /**
+     * Check if .github/copilot-instructions.md has Clavix block
+     */
+    static hasClavixBlock(): Promise<boolean>;
+}
+//# sourceMappingURL=copilot-instructions-generator.d.ts.map

package/dist/core/adapters/copilot-instructions-generator.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CopilotInstructionsGenerator = void 0;
+const file_system_1 = require("../../utils/file-system");
+const path = __importStar(require("path"));
+/**
+ * Generator for GitHub Copilot instructions file
+ * Provides workflow instructions via .github/copilot-instructions.md
+ */
+class CopilotInstructionsGenerator {
+    /**
+     * Generate or update .github/copilot-instructions.md with Clavix workflows
+     */
+    static async generate() {
+        const templatePath = path.join(__dirname, '../../templates/agents/copilot-instructions.md');
+        // Check if template exists
+        if (!(await file_system_1.FileSystem.exists(templatePath))) {
+            throw new Error(`Copilot instructions template not found at ${templatePath}`);
+        }
+        const template = await file_system_1.FileSystem.readFile(templatePath);
+        // Ensure .github directory exists
+        await file_system_1.FileSystem.ensureDir('.github');
+        // Inject into .github/copilot-instructions.md using managed blocks
+        await this.injectManagedBlock(this.TARGET_FILE, template);
+    }
+    /**
+     * Inject or update managed block in .github/copilot-instructions.md
+     */
+    static async injectManagedBlock(filePath, content) {
+        let fileContent = '';
+        // Read existing file or start with empty content
+        if (await file_system_1.FileSystem.exists(filePath)) {
+            fileContent = await file_system_1.FileSystem.readFile(filePath);
+        }
+        const blockRegex = new RegExp(`${this.escapeRegex(this.START_MARKER)}[\\s\\S]*?${this.escapeRegex(this.END_MARKER)}`, 'g');
+        const wrappedContent = `${this.START_MARKER}\n${content}\n${this.END_MARKER}`;
+        if (blockRegex.test(fileContent)) {
+            // Replace existing block
+            fileContent = fileContent.replace(blockRegex, wrappedContent);
+        }
+        else {
+            // Append new block
+            if (fileContent && !fileContent.endsWith('\n\n')) {
+                fileContent += '\n\n';
+            }
+            fileContent += wrappedContent + '\n';
+        }
+        await file_system_1.FileSystem.writeFileAtomic(filePath, fileContent);
+    }
+    /**
+     * Escape special regex characters
+     */
+    static escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * Check if .github/copilot-instructions.md has Clavix block
+     */
+    static async hasClavixBlock() {
+        if (!(await file_system_1.FileSystem.exists(this.TARGET_FILE))) {
+            return false;
+        }
+        const content = await file_system_1.FileSystem.readFile(this.TARGET_FILE);
+        return content.includes(this.START_MARKER);
+    }
+}
+exports.CopilotInstructionsGenerator = CopilotInstructionsGenerator;
+CopilotInstructionsGenerator.TARGET_FILE = '.github/copilot-instructions.md';
+CopilotInstructionsGenerator.START_MARKER = '<!-- CLAVIX:START -->';
+CopilotInstructionsGenerator.END_MARKER = '<!-- CLAVIX:END -->';
+//# sourceMappingURL=copilot-instructions-generator.js.map

package/dist/core/agent-manager.js

@@ -17,7 +17,6 @@ const gemini_adapter_1 = require("./adapters/gemini-adapter");
 const qwen_adapter_1 = require("./adapters/qwen-adapter");
 const codex_adapter_1 = require("./adapters/codex-adapter");
 const augment_adapter_1 = require("./adapters/augment-adapter");
-const copilot_adapter_1 = require("./adapters/copilot-adapter");
 /**
  * Agent Manager - handles agent detection and registration
  */
@@ -40,7 +39,6 @@ class AgentManager {
         this.registerAdapter(new gemini_adapter_1.GeminiAdapter());
         this.registerAdapter(new qwen_adapter_1.QwenAdapter());
         this.registerAdapter(new codex_adapter_1.CodexAdapter());
-        this.registerAdapter(new copilot_adapter_1.CopilotAdapter());
     }
     /**
      * Register a new agent adapter

package/dist/templates/agents/copilot-instructions.md

@@ -0,0 +1,90 @@
+# Clavix Workflows for GitHub Copilot
+
+These instructions enhance GitHub Copilot's understanding of the Clavix prompt engineering framework and workflow commands available in this project.
+
+## About Clavix
+
+Clavix is a CLEAR Framework-validated prompt engineering toolkit that helps improve prompts, generate PRDs, and manage implementation workflows. The CLEAR Framework (Concise, Logical, Explicit, Adaptive, Reflective) is an academically-validated approach developed by Dr. Leo Lo at the University of New Mexico.
+
+## Available Commands
+
+When working with this project, you can use the following Clavix commands:
+
+### Prompt Improvement
+- `clavix fast "<prompt>"` - Quick CLEAR analysis (C/L/E components) with improved prompt output
+- `clavix deep "<prompt>"` - Comprehensive CLEAR analysis (all 5 components: C/L/E/A/R) with alternatives and validation
+
+### Strategic Planning
+- `clavix prd` - Interactive PRD generation through Socratic questioning
+- `clavix plan` - Transform PRDs into phase-based implementation tasks
+- `clavix implement` - Execute tasks with progress tracking
+
+### Conversational Workflows
+- `clavix start` - Begin conversational session for requirements gathering
+- `clavix summarize [session-id]` - Extract mini-PRD and optimized prompts from sessions
+
+### Project Management
+- `clavix list` - List sessions and output projects
+- `clavix show [session-id]` - Inspect session or project details
+- `clavix archive [project]` - Archive or restore completed projects
+- `clavix update` - Refresh Clavix documentation and commands
+
+## Workflow Patterns
+
+### Quick Prompt Improvement
+1. User provides a rough prompt
+2. Run `clavix fast "<prompt>"` for quick CLEAR-validated improvements
+3. Use the optimized prompt for better results
+
+### Comprehensive Prompt Analysis
+1. User has a complex requirement
+2. Run `clavix deep "<prompt>"` for full CLEAR analysis
+3. Review alternative variations and validation checklists
+4. Select the best approach
+
+### Strategic Project Planning
+1. Run `clavix prd` to generate a comprehensive PRD through guided questions
+2. Run `clavix plan` to break down the PRD into implementation tasks
+3. Run `clavix implement` to execute tasks systematically
+4. Archive completed work with `clavix archive`
+
+### Conversational Requirements Gathering
+1. Run `clavix start` to begin capturing a conversation
+2. Discuss requirements naturally with the user
+3. Run `clavix summarize` to extract structured requirements and prompts
+
+## CLEAR Framework Components
+
+When analyzing or improving prompts, apply these CLEAR Framework principles:
+
+- **[C] Concise**: Remove verbosity, pleasantries, unnecessary qualifiers
+- **[L] Logical**: Ensure coherent sequencing (context → requirements → constraints → output)
+- **[E] Explicit**: Add clear specifications for persona, format, tone, success criteria
+- **[A] Adaptive**: Provide alternative phrasings and flexible structures
+- **[R] Reflective**: Include validation checklists and quality criteria
+
+## Output Locations
+
+Clavix stores artifacts in the `.clavix/` directory:
+- `.clavix/outputs/<project>/` - PRDs, tasks, and optimized prompts
+- `.clavix/sessions/` - Captured conversational sessions
+- `.clavix/templates/` - Custom template overrides
+- `.clavix/config.json` - Project configuration
+
+## Best Practices
+
+1. **Start with the right mode**: Use fast mode for simple prompts, deep mode for complex requirements, and PRD mode for strategic planning
+2. **Leverage CLEAR Framework**: Always consider the 5 CLEAR components when crafting prompts
+3. **Document requirements**: Use PRD workflow for significant features to ensure clear requirements
+4. **Track progress**: Use implement command to maintain structured task execution
+5. **Archive completed work**: Keep project organized by archiving finished projects
+
+## Integration with GitHub Copilot
+
+When users ask for help with prompts or requirements:
+1. Suggest running the appropriate Clavix command
+2. Explain the expected output and benefits
+3. Help interpret Clavix-generated outputs
+4. Apply CLEAR Framework principles in your responses
+
+This integration makes GitHub Copilot aware of Clavix workflows and can suggest using Clavix commands when appropriate.

package/dist/templates/slash-commands/amp/archive.md

@@ -47,7 +47,33 @@ You are helping the user archive completed PRD projects to keep their workspace
    - User wants to archive work-in-progress
    - Tasks are incomplete but project is done
 
-5. **List Archived Projects**:
+5. **Delete Project (Permanent Removal)**: **DESTRUCTIVE ACTION**
+   ```bash
+   clavix archive [project-name] --delete
+   ```
+
+   **WARNING**: This PERMANENTLY deletes the project. Cannot be restored.
+
+   **When to delete vs archive:**
+   - **DELETE**: Failed experiments, duplicate projects, test/demo data, abandoned prototypes with no value
+   - **ARCHIVE**: Completed work, incomplete but potentially useful work, anything you might reference later
+
+   **Delete decision tree:**
+   ```
+   Is this a failed experiment with no learning value? → DELETE
+   Is this a duplicate/test project with no unique info? → DELETE
+   Might you need to reference this code later? → ARCHIVE
+   Could this be useful for learning/reference? → ARCHIVE
+   Are you unsure? → ARCHIVE (safe default)
+   ```
+
+   **Safety confirmation required:**
+   - Shows project details and task status
+   - Requires typing project name to confirm
+   - Warns about permanent deletion
+   - Lists what will be permanently deleted
+
+6. **List Archived Projects**:
    ```bash
    clavix archive --list
    ```
@@ -63,14 +89,14 @@ You are helping the user archive completed PRD projects to keep their workspace
 
 ## When to Archive
 
-✅ **Good times to archive**:
+**Good times to archive:**
 - All implementation tasks are completed (`tasks.md` shows 100%)
 - Project has been deployed/shipped to production
 - Feature is complete and no more work planned
 - User explicitly requests archival
 - Old/abandoned projects that won't be continued
 
-❌ **Don't archive when**:
+**Don't archive when:**
 - Tasks are still in progress (unless using --force)
 - Project is actively being worked on
 - Future enhancements are planned in current tasks
@@ -131,6 +157,29 @@ You: "I'll restore it from the archive"
 Result: Project moved back to .clavix/outputs/user-authentication-system/
 ```
 
+### Workflow 4: Delete Failed Experiment
+```
+User: "I have a test project 'api-experiment-1' that I don't need anymore"
+You: "Is this something you might reference later, or can it be permanently deleted?"
+
+User: "It was just a quick test, no value. Delete it."
+You: "This will permanently delete the project. I'll run the delete command."
+
+     Run: clavix archive api-experiment-1 --delete
+
+System shows:
+  Project: api-experiment-1
+  Tasks: 3/5 completed
+  Files: full-prd.md, quick-prd.md, tasks.md
+
+  WARNING: This action is PERMANENT and CANNOT be undone.
+  Type the project name to confirm deletion: _
+
+User types: api-experiment-1
+
+Result: Project permanently deleted from .clavix/outputs/api-experiment-1/
+```
+
 ## AI Agent Guidelines
 
 When user mentions archiving or cleaning up projects:
@@ -155,6 +204,28 @@ When user mentions archiving or cleaning up projects:
    - Use `clavix archive --list` to show what's archived
    - Offer to restore if needed
 
+5. **Handle delete requests carefully**:
+   - Always ask if they want to delete or archive
+   - Explain that delete is permanent and irreversible
+   - Suggest archive as the safer default
+   - Use decision tree to help user decide
+   - Only proceed with `--delete` after clear confirmation
+   - Double-check it's truly no-value content (failed experiments, duplicates)
+
+## Workflow Navigation
+
+**You are here:** Archive (Project Cleanup)
+
+**Common workflows:**
+- **Complete workflow**: `/clavix:implement` → [all tasks done] → `/clavix:archive` → Clean workspace
+- **Review and archive**: `/clavix:archive` → [select completed project] → Archive
+- **Restore old work**: `/clavix:archive --list` → `/clavix:archive --restore [project]` → Resume
+
+**Related commands:**
+- `/clavix:implement` - Complete remaining tasks before archiving
+- `/clavix:plan` - Review task completion status
+- `/clavix:prd` - Start new project after archiving old one
+
 ## Tips
 
 - Archive keeps your active projects list clean and focused
@@ -162,3 +233,59 @@ When user mentions archiving or cleaning up projects:
 - Archive is searchable - you can still `grep` or find files in archive/
 - Regular archiving improves `/clavix:plan` and `/clavix:implement` performance
 - Use `--list` regularly to know what's been archived
+
+## Troubleshooting
+
+### Issue: No projects available to archive
+**Cause**: No projects in `.clavix/outputs/` OR all already archived
+**Solution**:
+- Run `clavix archive --list` to see archived projects
+- Check `.clavix/outputs/` for active projects
+- If none exist, no action needed
+
+### Issue: Trying to archive project with incomplete tasks
+**Cause**: User wants to archive but tasks aren't 100% done
+**Solution** (inline):
+- Warn: "Project has X incomplete tasks. Archive anyway?"
+- Show which tasks are incomplete
+- Suggest `--force` flag if user confirms
+- Recommend completing tasks first if they're actually unfinished (not scope-changed)
+
+### Issue: Cannot restore archived project (name conflict)
+**Cause**: Project with same name already exists in active outputs
+**Solution**:
+- Error: "Project '[name]' already exists in active outputs"
+- Suggest renaming one of them
+- Or archive the active one first, then restore
+- Or restore to different name (if CLI supports it)
+
+### Issue: Unsure whether to delete or archive
+**Cause**: User wants to clean up but uncertain about permanence
+**Solution**:
+- Use the decision tree in template
+- Default recommendation: ARCHIVE (safer)
+- Only suggest delete for: duplicates, failed experiments, test data
+- Remind: Archive is free, disk space is cheap, regret is expensive
+
+### Issue: Accidentally deleted project (used --delete instead of archive)
+**Cause**: User error or misunderstanding of --delete flag
+**Solution**:
+- Cannot be recovered from Clavix
+- Check if git history exists (if code was committed)
+- Check if user has backups
+- Learn: Use archive by default, delete only when absolutely certain
+
+### Issue: Archive directory getting too large
+**Cause**: Many archived projects accumulating
+**Solution**:
+- Archive is meant to grow - this is normal
+- Projects in archive don't affect performance
+- If truly concerned: Review archive, delete ancient/irrelevant projects
+- Or move very old archives to external backup storage
+
+### Issue: Archived project but forgot what it was about
+**Cause**: No naming convention or time passed
+**Solution**:
+- Read PRD in archived project: `.clavix/outputs/archive/[project]/full-prd.md`
+- PRD contains problem, goal, and features
+- Consider better naming conventions: date-feature format (e.g., "2024-01-user-auth")

package/dist/templates/slash-commands/amp/deep.md

@@ -31,21 +31,37 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
    - **Adaptiveness [A]**: Multiple variations and approaches
    - **Reflectiveness [R]**: Full validation and edge case analysis
 
-3. **Generate Comprehensive Output**:
+3. **Strategic Scope Detection** (before detailed analysis):
 
-   a. **📊 CLEAR Assessment** (all 5 components with scores)
+   **Check for strategic concerns** by identifying keywords/themes:
+   - **Architecture**: system design, microservices, monolith, architecture patterns, scalability patterns
+   - **Security**: authentication, authorization, encryption, security, OWASP, vulnerabilities, threat model
+   - **Scalability**: load balancing, caching, database scaling, performance optimization, high availability
+   - **Infrastructure**: deployment, CI/CD, DevOps, cloud infrastructure, containers, orchestration
+   - **Business Impact**: ROI, business metrics, KPIs, stakeholder impact, market analysis
 
-   b. **✨ CLEAR-Optimized Prompt** (applying all components)
+   **If 3+ strategic keywords detected**:
+   Ask the user: "I notice this involves strategic decisions around [detected themes]. These topics benefit from PRD-style planning with business context and architectural considerations. Would you like to:
+   - Switch to `/clavix:prd` for comprehensive strategic planning (recommended)
+   - Continue with deep mode for prompt-level analysis only"
 
-   c. **📝 CLEAR Changes Made** (labeled with [C], [L], [E], [A], [R])
+   **If user chooses to continue**, proceed with deep analysis but remind them at the end that `/clavix:prd` is available for strategic planning.
 
-   d. **🔄 Adaptive Variations [A]**:
+4. **Generate Comprehensive Output**:
+
+   a. **CLEAR Assessment** (all 5 components with scores)
+
+   b. **CLEAR-Optimized Prompt** (applying all components)
+
+   c. **CLEAR Changes Made** (labeled with [C], [L], [E], [A], [R])
+
+   d. **Adaptive Variations [A]**:
       - 2-3 alternative phrasings
       - Alternative structures (user story, job story, structured)
       - Temperature recommendations
       - Explain when each approach is most appropriate
 
-   e. **🤔 Reflection Checklist [R]**:
+   e. **Reflection Checklist [R]**:
       - Validation steps for accuracy
       - Edge cases to consider
       - "What could go wrong" analysis
@@ -62,14 +78,14 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
 
 ## Deep Mode Features
 
-✅ Include (Full CLEAR Framework):
+**Include (Full CLEAR Framework):**
 - **[C, L, E]**: All fast mode analysis (conciseness, logic, explicitness)
 - **[A] Adaptive**: Alternative phrasings, structures, flexibility, temperature
 - **[R] Reflective**: Validation checklist, edge cases, quality criteria, fact-checking
 - **CLEAR Assessment**: All 5 component scores
 - **CLEAR-labeled Changes**: Educational feedback showing which component improved what
 
-❌ Do NOT include (these belong in `/clavix:prd`):
+**Do NOT include (these belong in `/clavix:prd`):**
 - System architecture recommendations
 - Security best practices
 - Scalability strategy
@@ -101,12 +117,12 @@ Output:
 - How to handle session expiration during active use?
 
 ## Implementation Examples
-✅ Good:
+**Good:**
 - Prompt specifies authentication method, error handling, and accessibility requirements
 - Includes context about existing auth system and integration points
 - Defines measurable success criteria (load time, accessibility score)
 
-❌ Bad:
+**Bad:**
 - "Make a login page" - no context, constraints, or success criteria
 - Missing technical stack and integration requirements
 - No consideration of security or user experience
@@ -137,6 +153,20 @@ Output:
 - **Deep mode** (`/clavix:deep`): Full CLEAR (C, L, E, A, R) - comprehensive analysis with alternatives and validation
 - **PRD mode** (`/clavix:prd`): CLEAR-validated PRD generation - strategic planning with architecture decisions
 
+## Workflow Navigation
+
+**You are here:** Deep Mode (Comprehensive CLEAR Analysis)
+
+**Common workflows:**
+- **Thorough analysis**: `/clavix:deep` → Use optimized prompt + alternatives
+- **Escalate to strategic**: `/clavix:deep` → (detects strategic scope) → `/clavix:prd` → Plan → Implement → Archive
+- **From fast mode**: `/clavix:fast` → (suggests) `/clavix:deep` → Full analysis with A & R components
+
+**Related commands:**
+- `/clavix:fast` - Quick CLEAR improvements (C, L, E only)
+- `/clavix:prd` - Strategic PRD generation for architecture/business decisions
+- `/clavix:start` - Conversational mode for exploring unclear requirements
+
 ## Tips
 
 - **Apply full CLEAR framework** systematically: all 5 components
@@ -145,3 +175,33 @@ Output:
 - Use **[A] Adaptive** to explore alternative approaches
 - Use **[R] Reflective** to identify edge cases and validation needs
 - For architecture, security, and scalability, recommend `/clavix:prd`
+
+## Troubleshooting
+
+### Issue: Strategic scope detected but user wants to continue with deep mode
+**Cause**: User prefers deep analysis over PRD generation
+**Solution**:
+- Proceed with deep mode as requested
+- Remind at end that `/clavix:prd` is available for strategic planning
+- Focus on prompt-level CLEAR analysis, exclude architecture recommendations
+
+### Issue: Too many alternative variations making output overwhelming
+**Cause**: Adaptive component generating many options
+**Solution**:
+- Limit to 2-3 most distinct alternatives
+- Focus on meaningfully different approaches (not minor wording changes)
+- Group similar variations together
+
+### Issue: Reflective validation finding too many edge cases
+**Cause**: Complex prompt with many potential failure modes
+**Solution**:
+- Prioritize most likely or highest-impact edge cases
+- Group related edge cases
+- Suggest documenting all edge cases in PRD for complex projects
+
+### Issue: Deep analysis still feels insufficient for complex project
+**Cause**: Project needs strategic planning, not just prompt analysis
+**Solution**:
+- Switch to `/clavix:prd` for comprehensive planning
+- Deep mode is for prompts, PRD mode is for projects
+- Use PRD workflow: PRD → Plan → Implement