clavix 2.1.2 → 2.3.0

package/dist/templates/slash-commands/claude-code/start.md

@@ -24,7 +24,9 @@ You are starting a Clavix conversational session for iterative prompt and requir
    - Help them think through user needs
    - Identify potential challenges
 
-3. Keep track of key points discussed:
+3. **Track conversation topics and manage complexity**:
+
+   **Key points to track:**
    - Problem statement
    - Target users
    - Core features
@@ -32,6 +34,27 @@ You are starting a Clavix conversational session for iterative prompt and requir
    - Success criteria
    - Constraints and scope
 
+   **Multi-topic detection** (track distinct topics being discussed):
+   - Consider topics distinct if they address different problems/features/user needs
+   - Examples: "dashboard for sales" + "API for integrations" + "mobile app" = 3 topics
+
+   **When 3+ distinct topics detected**:
+   Auto-suggest focusing: "I notice we're discussing multiple distinct areas: [Topic A: summary], [Topic B: summary], and [Topic C: summary]. To ensure we develop clear requirements for each, would you like to:
+   - **Focus on one** - Pick the most important topic to explore thoroughly first
+   - **Continue multi-topic** - We'll track all of them, but the resulting prompt may need refinement
+   - **Create separate sessions** - Start fresh for each topic with dedicated focus"
+
+   **Complexity indicators** (suggest wrapping up/summarizing):
+   - Conversation > 15 exchanges
+   - Requirements for 5+ major features discussed
+   - Multiple technology stacks mentioned
+   - Significant scope changes or pivots occurred
+
+   When complexity threshold reached: "We've covered substantial ground. Would you like to:
+   - Continue exploring
+   - Use `/clavix:summarize` to extract what we have so far
+   - Switch to `/clavix:prd` for more structured planning"
+
 4. Be conversational and supportive:
    - Don't interrogate - have a natural discussion
    - Build on their ideas
@@ -61,6 +84,59 @@ After the conversational session, `/clavix:summarize` will:
 
 [Continue conversational refinement...]
 
+## Workflow Navigation
+
+**You are here:** Conversational Mode (Iterative Exploration)
+
+**Common workflows:**
+- **Exploration to prompt**: `/clavix:start` → [conversation] → `/clavix:summarize` → CLEAR-optimized prompt
+- **Exploration to PRD**: `/clavix:start` → [conversation] → `/clavix:prd` (answer questions with discussed info)
+- **Exploration to planning**: `/clavix:start` → `/clavix:summarize` → `/clavix:plan` → Implement
+
+**Related commands:**
+- `/clavix:summarize` - Extract and CLEAR-optimize conversation (typical next step)
+- `/clavix:prd` - Switch to structured PRD generation
+- `/clavix:fast` or `/clavix:deep` - Direct prompt improvement instead of conversation
+
 ## Note
 
 The goal is natural exploration of requirements, not a rigid questionnaire. Follow the user's lead while gently guiding toward clarity.
+
+## Troubleshooting
+
+### Issue: Conversation going in circles without progress
+**Cause**: Unclear focus or too many topics being explored
+**Solution** (inline):
+- Pause and summarize: "So far we've discussed [A], [B], [C]. Which should we focus on?"
+- Suggest focusing on one topic at a time
+- Or suggest `/clavix:summarize` to extract what's been discussed
+
+### Issue: User provides very high-level descriptions ("build something cool")
+**Cause**: User hasn't crystallized their ideas yet
+**Solution**:
+- Ask open-ended questions: "What made you think of this?"
+- Probe for use cases: "Walk me through how someone would use this"
+- Be patient - this mode is for exploration
+- Multiple exchanges are normal and expected
+
+### Issue: Detecting 3+ distinct topics but user keeps adding more
+**Cause**: Brainstorming mode or unclear priorities
+**Solution** (inline):
+- Interrupt after 3+ topics detected (per multi-topic protocol)
+- Strongly suggest focusing on one topic
+- Alternative: Document all topics and help prioritize
+- Consider suggesting `/clavix:prd` for each topic separately
+
+### Issue: Conversation exceeds 20 exchanges without clarity
+**Cause**: Too exploratory without convergence
+**Solution**:
+- Suggest wrapping up: "We've covered a lot. Ready to `/clavix:summarize`?"
+- Or pivot to `/clavix:prd` for structured planning
+- Or focus conversation: "Let's nail down the core problem first"
+
+### Issue: User wants to switch topics mid-conversation
+**Cause**: New idea occurred or original topic wasn't right
+**Solution**:
+- Note what was discussed so far
+- Ask: "Should we continue with [original topic] or switch to [new topic]?"
+- Suggest summarizing current topic first before switching

package/dist/templates/slash-commands/claude-code/summarize.md

@@ -9,15 +9,35 @@ You are analyzing the conversation history and extracting optimized requirements
 
 ## Instructions
 
-1. Review the entire conversation and identify:
-   - **Problem/Goal**: What is the user trying to build or solve?
-   - **Key Requirements**: What features and functionality were discussed?
-   - **Technical Constraints**: Any technologies, integrations, or performance needs?
-   - **User Needs**: Who are the end users and what do they need?
-   - **Success Criteria**: How will success be measured?
-   - **Context**: Any important background or constraints?
-
-2. Generate TWO outputs:
+1. **Pre-Extraction Validation** - Check conversation completeness:
+
+   **Minimum viable requirements:**
+   - **Objective/Goal**: Is there a clear problem or goal stated?
+   - **Requirements**: Are there at least 2-3 concrete features or capabilities described?
+   - **Context**: Is there enough context about who/what/why?
+
+   **If missing critical elements:**
+   - Identify what's missing (e.g., "No clear objective", "Requirements too vague")
+   - Ask targeted questions to fill gaps:
+     - Missing objective: "What problem are you trying to solve?"
+     - Vague requirements: "Can you describe 2-3 specific things this should do?"
+     - No context: "Who will use this and in what situation?"
+   - **DO NOT** proceed to extraction until minimum viable requirements met
+
+   **Confidence indicators** (annotate extracted elements):
+   - **[HIGH]**: Explicitly stated multiple times with details
+   - **[MEDIUM]**: Mentioned once or inferred from context
+   - **[LOW]**: Assumed based on limited information
+
+2. Review the entire conversation and identify (with confidence indicators):
+   - **Problem/Goal** [confidence]: What is the user trying to build or solve?
+   - **Key Requirements** [confidence per requirement]: What features and functionality were discussed?
+   - **Technical Constraints** [confidence]: Any technologies, integrations, or performance needs?
+   - **User Needs** [confidence]: Who are the end users and what do they need?
+   - **Success Criteria** [confidence]: How will success be measured?
+   - **Context** [confidence]: Any important background or constraints?
+
+3. Generate TWO outputs:
 
    **Mini-PRD** (structured document):
    ```markdown
@@ -52,12 +72,18 @@ You are analyzing the conversation history and extracting optimized requirements
    [Success criteria and any important context]
    ```
 
-3. **CLEAR Framework Optimization** (automatic):
-   - After extracting the optimized prompt, it's analyzed using CLEAR framework
-   - Applies Conciseness, Logic, and Explicitness enhancements
-   - Displays both raw extraction and CLEAR-enhanced version
-   - Shows CLEAR scores and improvements made
-   - Saves CLEAR-optimized version as `clear-optimized-prompt.md`
+3. **CLEAR Framework Optimization** (automatic with labeled improvements):
+   - After extracting the optimized prompt, analyze using CLEAR framework
+   - Apply Conciseness, Logic, and Explicitness enhancements
+   - **Label all improvements** with CLEAR component tags:
+     - **[C]**: "Removed 12 conversational words, reduced from 45 to 28 words"
+     - **[L]**: "Restructured flow: context → requirements → constraints → success criteria"
+     - **[E]**: "Added explicit output format (React component), persona (senior dev), success metrics (load time < 2s)"
+   - Display both raw extraction and CLEAR-enhanced version
+   - Show CLEAR scores (before/after) and labeled improvements
+   - Save both versions:
+     - `optimized-prompt.md` (raw extraction)
+     - `clear-optimized-prompt.md` (CLEAR-enhanced with improvement notes)
 
 4. Highlight key insights discovered during the conversation.
 
@@ -78,12 +104,26 @@ You are analyzing the conversation history and extracting optimized requirements
 
 ## Quality Checks
 
-- ✅ Clear objective stated
-- ✅ Specific, actionable requirements
-- ✅ Technical constraints identified
-- ✅ Success criteria defined
-- ✅ User needs considered
-- ✅ CLEAR framework applied for AI consumption
+- Clear objective stated
+- Specific, actionable requirements
+- Technical constraints identified
+- Success criteria defined
+- User needs considered
+- CLEAR framework applied for AI consumption
+
+## Workflow Navigation
+
+**You are here:** Summarize (Conversation Extraction)
+
+**Common workflows:**
+- **Standard flow**: `/clavix:start` → [conversation] → `/clavix:summarize` → Use CLEAR-optimized prompt
+- **To implementation**: `/clavix:summarize` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
+- **Standalone use**: [Any conversation] → `/clavix:summarize` → Extract and optimize
+
+**Related commands:**
+- `/clavix:start` - Begin conversational exploration (typical previous step)
+- `/clavix:plan` - Generate tasks from extracted mini-PRD (next step)
+- `/clavix:fast` or `/clavix:deep` - Further optimize the extracted prompt
 
 ## Example
 
@@ -97,3 +137,43 @@ Technical stack: React + TypeScript frontend, integrate with existing Salesforce
 
 Success: Sales managers can identify issues within 30 seconds of opening, dashboard loads in <2 seconds, 90% of team uses it daily within first month.
 ```
+
+## Troubleshooting
+
+### Issue: Pre-extraction validation fails (missing objective/requirements)
+**Cause**: Conversation didn't cover enough detail
+**Solution** (inline - DO NOT extract):
+- List what's missing specifically
+- Ask targeted questions to fill gaps
+- Only proceed to extraction after minimum viable requirements met
+- Show confidence indicators for what WAS discussed
+
+### Issue: Conversation covered multiple unrelated topics
+**Cause**: Exploratory discussion without focus
+**Solution**:
+- Ask user which topic to extract/focus on
+- Or extract all topics separately into different sections
+- Mark multi-topic extraction with [MULTI-TOPIC] indicator
+- Suggest breaking into separate PRDs for each topic
+
+### Issue: CLEAR optimization doesn't significantly improve extracted prompt
+**Cause**: Conversation was already well-structured and detailed
+**Solution**:
+- Minor improvements are normal for good conversations
+- Show CLEAR scores (should be high: >80%)
+- Still provide both versions but note that original extraction was already CLEAR
+
+### Issue: Low confidence indicators across all extracted elements
+**Cause**: Conversation was too vague or high-level
+**Solution** (inline):
+- Don't just extract with [LOW] markers everywhere
+- Ask follow-up questions to increase confidence
+- Or inform user: "Our conversation was exploratory. I recommend `/clavix:start` to go deeper, or `/clavix:prd` for structured planning"
+
+### Issue: Extracted prompt contradicts earlier conversation
+**Cause**: Requirements evolved during conversation
+**Solution**:
+- Use latest/final version of requirements
+- Note that requirements evolved
+- Ask user to confirm which version is correct
+- Suggest starting fresh with `/clavix:prd` if major contradictions exist

package/dist/templates/slash-commands/cline/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/cline/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

package/dist/templates/slash-commands/cline/fast.md

@@ -29,15 +29,25 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
    - **Logic [L]**: Check sequencing and flow - is information presented coherently?
    - **Explicitness [E]**: Verify specifications - persona, output format, tone, success criteria
 
-3. **CLEAR-Aware Smart Triage**: Check if the prompt needs deep analysis:
-   - Is it less than 20 characters?
-   - Missing 3+ critical elements (context, tech stack, success criteria, user needs, expected output)?
-   - Contains vague scope words ("app", "system", "project") without context?
-   - **Low CLEAR scores** (Conciseness < 60%, Logic < 60%, Explicitness < 50%)
+3. **CLEAR-Aware Smart Triage**: Use multi-factor content-quality assessment to determine if deep analysis is needed:
 
-   If YES to any: **Recommend `/clavix:deep` instead** and explain which CLEAR component needs deeper analysis. Ask the user if they want to:
-   - Switch to deep mode (recommended)
-   - Continue with fast mode (at their own risk)
+   **Primary Indicators** (CLEAR scores - most important):
+   - **Low CLEAR scores**: Conciseness < 60%, Logic < 60%, or Explicitness < 50%
+
+   **Secondary Indicators** (content quality):
+   - **Missing critical elements**: 3+ missing from (context, tech stack, success criteria, user needs, expected output)
+   - **Scope clarity**: Contains vague words ("app", "system", "project", "feature") without defining what/who/why
+   - **Requirement completeness**: Lacks actionable requirements or measurable outcomes
+   - **Context depth**: Extremely brief (<15 words) OR overly verbose (>100 words without structure)
+
+   **Escalation Decision**:
+   - If **Low CLEAR scores** + **2+ Secondary Indicators**: **Strongly recommend `/clavix:deep`**
+   - If **Low CLEAR scores** only: **Suggest `/clavix:deep`** but can proceed with fast mode
+   - Explain which CLEAR component needs deeper analysis and why
+
+   Ask the user:
+   - Switch to deep mode (recommended when strongly recommended)
+   - Continue with fast mode (acceptable for suggestion-level, but at their own risk for strong recommendation)
 
 4. Generate a **CLEAR-optimized** structured prompt with these sections:
    **Objective**: Clear, specific goal
@@ -55,13 +65,13 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
 
 ## Fast Mode Features
 
-✅ Include (CLEAR C, L, E):
+**Include (CLEAR C, L, E):**
 - **CLEAR Assessment** (Conciseness, Logic, Explicitness scores with issues)
 - Single CLEAR-optimized improved prompt
 - **CLEAR Changes Made** (labeled with [C], [L], [E] components)
 - Recommendation to use deep mode for Adaptive & Reflective components
 
-❌ Skip (use `/clavix:deep` instead):
+**Skip (use `/clavix:deep` instead):**
 - **[A] Adaptive**: Alternative phrasings, structures, flexibility
 - **[R] Reflective**: Validation checklists, edge cases, quality criteria
 - Strategic analysis (architecture, security - that's for `/clavix:prd`)
@@ -72,9 +82,9 @@ If user provides: "Please could you maybe help me create a login page?"
 
 Output:
 ```
-## 🎯 CLEAR Analysis (Fast Mode)
+## CLEAR Analysis (Fast Mode)
 
-### 📊 CLEAR Framework Assessment:
+### CLEAR Framework Assessment:
 
 [C] Conciseness: 45%
     • 4 unnecessary pleasantries detected ("Please", "could you", "maybe", "help me")
@@ -90,11 +100,11 @@ Output:
 
 Overall CLEAR Score: 51% (needs-improvement)
 
-💡 Recommendation:
+Recommendation:
 For Adaptive variations (A) and Reflective validation (R), use:
   clavix deep "<your prompt>"
 
-### ✨ CLEAR-Optimized Prompt:
+### CLEAR-Optimized Prompt:
 
 Objective: Build a secure user authentication login page
 
@@ -119,13 +129,27 @@ Success Criteria:
 - Invalid credentials show appropriate errors
 - Page is accessible via keyboard navigation
 
-### 📝 CLEAR Changes Made:
+### CLEAR Changes Made:
 
 [C] Removed 4 pleasantries ("Please", "could you", "maybe", "help me"), reduced from 11 words to core intent
 [L] Structured logical flow: Objective → Requirements → Technical Constraints → Expected Output → Success Criteria
 [E] Added explicit specifications: React TypeScript persona, component output format, production-ready tone, accessibility criteria
 ```
 
+## Workflow Navigation
+
+**You are here:** Fast Mode (Quick CLEAR Improvement)
+
+**Common workflows:**
+- **Quick cleanup**: `/clavix:fast` → Use improved prompt
+- **Need more depth**: `/clavix:fast` → (suggests) `/clavix:deep` → Comprehensive analysis
+- **Strategic planning**: `/clavix:fast` → (suggests) `/clavix:prd` → Plan → Implement → Archive
+
+**Related commands:**
+- `/clavix:deep` - Full CLEAR analysis (all 5 components: C, L, E, A, R)
+- `/clavix:prd` - Generate PRD for strategic planning
+- `/clavix:start` - Conversational exploration before prompting
+
 ## Tips
 
 - **Apply CLEAR framework** systematically: C, L, E components
@@ -134,3 +158,26 @@ Success Criteria:
 - For comprehensive analysis with [A] and [R], recommend `/clavix:deep`
 - For strategic planning, recommend `/clavix:prd`
 - Focus on making prompts **CLEAR** quickly
+
+## Troubleshooting
+
+### Issue: Triage keeps recommending deep mode
+**Cause**: Prompt has low CLEAR scores + multiple secondary indicators
+**Solution**:
+- Accept the recommendation - deep mode will provide better analysis
+- OR improve prompt manually before running fast mode again
+- Check which CLEAR component is scoring low and address it
+
+### Issue: Can't determine if prompt is complex enough for deep mode
+**Cause**: Borderline CLEAR scores or unclear content quality
+**Solution**:
+- Err on side of fast mode first
+- If output feels insufficient, escalate to `/clavix:deep`
+- Use triage as guidance, not absolute rule
+
+### Issue: Improved prompt still feels incomplete
+**Cause**: Fast mode only applies C, L, E components
+**Solution**:
+- Use `/clavix:deep` for Adaptive variations and Reflective validation
+- OR use `/clavix:prd` if strategic planning is needed
+- Fast mode is for quick cleanup, not comprehensive analysis