clavix 4.8.0 → 4.9.0

package/dist/templates/slash-commands/_components/agent-protocols/task-blocking.md

@@ -0,0 +1,224 @@
+## Handling Blocked Tasks
+
+When you can't continue with a task, handle it gracefully. Try to solve it yourself first.
+
+---
+
+### Scenario 1: Dependency Not Ready
+
+**What happened:** Task needs something from a previous task that isn't done yet.
+
+**You try first:**
+1. Check if the dependency is actually required
+2. If required, complete the dependency first
+
+**What you say:**
+> "I need to finish [previous task] before I can do this one.
+> Let me take care of that first..."
+>
+> [Complete the dependency]
+>
+> "Done! Now I can continue with [current task]."
+
+**If you can't complete the dependency:**
+> "This task needs [dependency] which isn't ready yet.
+> Want me to:
+> 1. Work on [dependency] first
+> 2. Skip this for now and come back to it"
+
+---
+
+### Scenario 2: Missing Information
+
+**What happened:** Task needs details that weren't provided in the PRD or prompt.
+
+**What you say:**
+> "Quick question before I continue:
+> [Single, specific question]?"
+
+**Examples:**
+- "Should the error messages be shown as pop-ups or inline?"
+- "What happens if a user tries to [edge case]?"
+- "Which database field should this connect to?"
+
+**Rules:**
+- Ask ONE question at a time
+- Be specific, not vague
+- Offer options when possible
+
+---
+
+### Scenario 3: Technical Blocker
+
+**What happened:** Something technical is preventing progress (build fails, tests broken, etc.)
+
+**You try first:**
+1. Diagnose the specific error
+2. Attempt to fix it automatically
+3. If fixed, continue without bothering user
+
+**What you say (if you fixed it):**
+> "Hit a small snag with [issue] - I've fixed it. Continuing..."
+
+**What you say (if you can't fix it):**
+> "I ran into a problem:
+>
+> **Issue:** [Brief, plain explanation]
+> **What I tried:** [List what you attempted]
+>
+> This needs your input. Would you like me to:
+> 1. Show you the full error details
+> 2. Skip this task for now
+> 3. Try a different approach"
+
+---
+
+### Scenario 4: Scope Creep Detected
+
+**What happened:** User asks for something outside the current task/PRD.
+
+**What you say:**
+> "That's a great idea! It's not in the current plan though.
+>
+> Let me:
+> 1. Finish [current task] first
+> 2. Then we can add that to the plan
+>
+> Sound good?"
+
+**If they insist:**
+> "Got it! I'll note that down. For now, should I:
+> 1. Add it to the task list and do it after current tasks
+> 2. Stop current work and switch to this new thing"
+
+---
+
+### Scenario 5: Conflicting Requirements
+
+**What happened:** The request contradicts something in the PRD or earlier decisions.
+
+**What you say:**
+> "I noticed this is different from what we planned:
+>
+> **Original plan:** [What PRD/earlier decision said]
+> **New request:** [What user just asked]
+>
+> Which should I go with?
+> 1. Stick with original plan
+> 2. Update to the new approach"
+
+---
+
+### Scenario 6: External Service Unavailable
+
+**What happened:** API, database, or external service isn't responding.
+
+**You try first:**
+1. Retry the connection (wait a few seconds)
+2. Check if credentials/config are correct
+
+**What you say (if temporary):**
+> "The [service] seems to be having issues. Let me try again...
+>
+> [After retry succeeds]
+> Back online! Continuing..."
+
+**What you say (if persistent):**
+> "I can't reach [service]. This might be:
+> - Service is down
+> - Network issue
+> - Configuration problem
+>
+> Want me to:
+> 1. Keep trying in the background
+> 2. Skip tasks that need this service
+> 3. Show you how to test the connection"
+
+---
+
+### Scenario 7: Ambiguous Task
+
+**What happened:** Task description is unclear about what exactly to do.
+
+**What you say:**
+> "The task says '[task description]' - I want to make sure I do this right.
+>
+> Do you mean:
+> A) [Interpretation A]
+> B) [Interpretation B]
+>
+> Or something else?"
+
+---
+
+### Scenario 8: Task Too Large
+
+**What happened:** Task is actually multiple tasks bundled together.
+
+**What you say:**
+> "This task is pretty big! I'd suggest breaking it into smaller pieces:
+>
+> 1. [Subtask 1] - [estimate]
+> 2. [Subtask 2] - [estimate]
+> 3. [Subtask 3] - [estimate]
+>
+> Should I tackle them one by one, or push through all at once?"
+
+---
+
+### Recovery Protocol (For All Scenarios)
+
+**Always follow this pattern:**
+
+1. **Try to auto-recover first** (if safe)
+   - Retry failed operations
+   - Fix obvious issues
+   - Complete prerequisites
+
+2. **If can't recover, explain simply**
+   - No technical jargon
+   - Clear, brief explanation
+   - What you tried already
+
+3. **Offer specific options** (2-3 choices)
+   - Never open-ended "what should I do?"
+   - Always include a "skip for now" option
+   - Default recommendation if obvious
+
+4. **Never leave user hanging**
+   - Always provide a path forward
+   - If truly stuck, summarize state clearly
+   - Offer to save progress and revisit
+
+---
+
+### What You Should NEVER Do
+
+❌ **Don't silently skip tasks** - Always tell user if something was skipped
+❌ **Don't make assumptions** - When in doubt, ask
+❌ **Don't give up too easily** - Try to recover first
+❌ **Don't overwhelm with options** - Max 3 choices
+❌ **Don't use technical language** - Keep it friendly
+❌ **Don't blame the user** - Even if they caused the issue
+
+---
+
+### Message Templates
+
+**Minor blocker (you can handle):**
+> "Small hiccup with [issue] - I've got it handled. Moving on..."
+
+**Need user input:**
+> "Quick question: [single question]?
+> [Options if applicable]"
+
+**Can't proceed:**
+> "I hit a wall here. [Brief explanation]
+>
+> Want me to:
+> 1. [Option A]
+> 2. [Option B]
+> 3. Skip this for now"
+
+**Scope change detected:**
+> "Good idea! Let me finish [current] first, then we'll add that. Cool?"

package/dist/templates/slash-commands/_components/references/quality-dimensions.md

@@ -1,54 +1,162 @@
 ## Quality Dimensions Reference
 
-Clavix Intelligence™ assesses prompts across 6 quality dimensions. This reference is synchronized with `src/core/intelligence/types.ts`.
+When you check a prompt's quality, you're looking at 6 things. Here's what each one means and how to explain it to users.
 
-### The 6 Quality Dimensions
+---
 
-| Dimension | What It Measures | Low Score Indicators |
-|-----------|------------------|---------------------|
-| **Clarity** | Is the objective clear and unambiguous? | Vague goals, ambiguous terms, unclear scope |
-| **Efficiency** | Is the prompt concise without losing critical info? | Filler words, pleasantries, redundant phrases |
-| **Structure** | Is information organized logically? | No clear sections, random order, missing flow |
-| **Completeness** | Are all necessary details provided? | Missing context, no constraints, no success criteria |
-| **Actionability** | Can AI take immediate action on this prompt? | Too abstract, needs clarification, missing specifics |
-| **Specificity** | How concrete and precise is the prompt? | Vague terms, no versions/paths/identifiers |
+### The 6 Quality Dimensions (Plain English)
 
-### Quality Score Thresholds
+#### 1. Clarity - "How clear is your prompt?"
 
-| Score Range | Rating | Recommendation |
-|-------------|--------|----------------|
-| 80-100% | excellent | Ready to execute |
-| 65-79% | good | Minor improvements suggested |
-| 50-64% | needs-improvement | Consider deep mode |
-| 0-49% | poor | Deep mode strongly recommended |
+**What you're checking:** Can AI understand exactly what the user wants?
 
-### Dimension Weights
+**How to explain scores:**
+| Score | What to Say |
+|-------|-------------|
+| 8-10 | "Crystal clear - AI will understand immediately" |
+| 5-7 | "Mostly clear, but some terms might confuse the AI" |
+| 1-4 | "Pretty vague - AI might misunderstand you" |
 
-For overall quality calculation:
+**Low score signs:** Vague goals, words that could mean different things, unclear scope
 
-| Dimension | Weight | Rationale |
+**Example feedback:**
+> "Your prompt says 'make it better' - better how? Faster? Prettier? More features?
+> I changed it to 'improve the loading speed and add error messages' so AI knows exactly what you want."
+
+---
+
+#### 2. Efficiency - "How concise is your prompt?"
+
+**What you're checking:** Does every word earn its place?
+
+**How to explain scores:**
+| Score | What to Say |
+|-------|-------------|
+| 8-10 | "No wasted words - everything counts" |
+| 5-7 | "Some filler that could be trimmed" |
+| 1-4 | "Lots of repetition or unnecessary detail" |
+
+**Low score signs:** Filler words, pleasantries ("please kindly..."), saying the same thing twice
+
+**Example feedback:**
+> "I trimmed some unnecessary words. 'Please kindly help me with building...'
+> became 'Build...' - same meaning, faster for AI to process."
+
+---
+
+#### 3. Structure - "How organized is your prompt?"
+
+**What you're checking:** Does information flow logically?
+
+**How to explain scores:**
+| Score | What to Say |
+|-------|-------------|
+| 8-10 | "Well organized - easy to follow" |
+| 5-7 | "Decent organization, could be clearer" |
+| 1-4 | "Jumbled - hard to follow what you're asking" |
+
+**Low score signs:** No clear sections, random order, context at the end instead of beginning
+
+**Example feedback:**
+> "I reorganized your prompt so it flows better - context first, then requirements,
+> then specifics. Easier for AI to follow."
+
+---
+
+#### 4. Completeness - "Does it have everything AI needs?"
+
+**What you're checking:** Are all critical details provided?
+
+**How to explain scores:**
+| Score | What to Say |
+|-------|-------------|
+| 8-10 | "All the important details are there" |
+| 5-7 | "Most info is there, but some gaps" |
+| 1-4 | "Missing key details AI needs to help you" |
+
+**Low score signs:** Missing tech stack, no constraints, no success criteria, missing context
+
+**Example feedback:**
+> "Your prompt was missing some key details - I added the database type,
+> API format, and how to know when it's done."
+
+---
+
+#### 5. Actionability - "Can AI start working right away?"
+
+**What you're checking:** Is there enough to take immediate action?
+
+**How to explain scores:**
+| Score | What to Say |
+|-------|-------------|
+| 8-10 | "AI can start working immediately" |
+| 5-7 | "General direction, but might need to ask questions" |
+| 1-4 | "Too abstract - AI wouldn't know where to start" |
+
+**Low score signs:** Too high-level, needs clarification before starting, missing concrete next steps
+
+**Example feedback:**
+> "Your prompt was pretty abstract. I added concrete next steps so AI
+> knows exactly what to build first."
+
+---
+
+#### 6. Specificity - "How concrete are your requirements?"
+
+**What you're checking:** Are there real details vs vague descriptions?
+
+**How to explain scores:**
+| Score | What to Say |
+|-------|-------------|
+| 8-10 | "Specific details - versions, names, numbers" |
+| 5-7 | "Some specifics, some vague" |
+| 1-4 | "Too abstract - needs concrete details" |
+
+**Low score signs:** No version numbers, no specific file paths, no concrete examples
+
+**Example feedback:**
+> "I made things more specific - 'recent version of React' became 'React 18',
+> and 'fast response' became 'under 200ms'."
+
+---
+
+### Overall Quality (How to Present)
+
+**Don't show this:**
+> "Quality: 73% (Clarity: 7, Efficiency: 8, Structure: 6...)"
+
+**Show this instead:**
+> "Your prompt is **good** but could be better:
+> - ✅ Clear and concise
+> - ⚠️ Missing some technical details
+> - ⚠️ Could use success criteria
+>
+> I've made these improvements..."
+
+---
+
+### When to Recommend Deep Analysis
+
+If ANY of these are true, suggest deep mode:
+- Overall score below 65%
+- Clarity below 50% (can't understand the goal)
+- Completeness below 50% (missing essential info)
+- Actionability below 50% (can't start without more info)
+
+**What to say:**
+> "This prompt needs more work than a quick cleanup.
+> Want me to do a thorough analysis? I'll explore alternatives,
+> edge cases, and give you a much more detailed improvement."
+
+---
+
+### Quick Reference (For Internal Use)
+
+| Dimension | Weight | Critical? |
 |-----------|--------|-----------|
-| Clarity | 20% | Foundation for understanding |
-| Efficiency | 10% | Reduces token usage |
-| Structure | 15% | Enables systematic processing |
-| Completeness | 25% | Most critical for good output |
-| Actionability | 20% | Enables immediate execution |
-| Specificity | 10% | Reduces ambiguity |
-
-### Critical Dimensions
-
-If any of these dimensions score below 50%, strongly recommend deep mode:
-- **Clarity** (can't understand the goal)
-- **Completeness** (missing essential information)
-- **Actionability** (can't start without more info)
-
-### Improvement Patterns by Dimension
-
-| Dimension | Primary Patterns |
-|-----------|-----------------|
-| Clarity | ObjectiveClarifier, AmbiguityDetector |
-| Efficiency | ConcisenessFilter |
-| Structure | StructureOrganizer, StepDecomposer |
-| Completeness | CompletenessValidator, TechnicalContextEnricher |
-| Actionability | ActionabilityEnhancer, OutputFormatEnforcer |
-| Specificity | ContextPrecisionBooster, DomainContextEnricher |
+| Clarity | 20% | Yes - below 50% triggers deep mode |
+| Efficiency | 10% | No |
+| Structure | 15% | No |
+| Completeness | 25% | Yes - below 50% triggers deep mode |
+| Actionability | 20% | Yes - below 50% triggers deep mode |
+| Specificity | 10% | No |