clavix 4.8.1 → 4.10.0

package/dist/templates/slash-commands/_components/sections/pattern-impact.md

@@ -0,0 +1,208 @@
+## What Made the Biggest Difference
+
+When showing improvements, categorize by impact so users understand the value.
+
+---
+
+### Impact Categories
+
+#### High-Impact Improvements (Made a Big Difference)
+
+These changes significantly improve how well the AI will understand and respond.
+
+| Icon | Improvement | What It Means |
+|------|-------------|---------------|
+| 🎯 | **Made your goal clearer** | AI now knows exactly what you want |
+| 📋 | **Added missing details** | Filled gaps that would have confused AI |
+| ✂️ | **Removed confusing parts** | Took out things that were sending mixed signals |
+| 🔍 | **Fixed vague language** | Changed "make it good" to specific requirements |
+| ⚠️ | **Spotted potential problems** | Added handling for edge cases |
+
+**Show these first - they matter most.**
+
+#### Medium-Impact Improvements (Helpful Polish)
+
+These changes make the prompt better but weren't critical.
+
+| Icon | Improvement | What It Means |
+|------|-------------|---------------|
+| 📐 | **Better organization** | Rearranged for easier understanding |
+| 🏷️ | **Clearer labels** | Added sections so AI can scan quickly |
+| ✅ | **Added success criteria** | AI knows when it's done |
+| 🔄 | **Made it more specific** | General → Concrete details |
+| 📊 | **Added context** | Background info that helps AI understand |
+
+**Show these second - nice improvements.**
+
+#### Light Polish (Small but Nice)
+
+These are minor tweaks that add a bit of quality.
+
+| Icon | Improvement | What It Means |
+|------|-------------|---------------|
+| 💬 | **Smoother wording** | Reads better, same meaning |
+| 🧹 | **Cleaned up formatting** | Easier to read |
+| 📝 | **Minor clarifications** | Small details filled in |
+
+**Mention briefly or skip if too minor.**
+
+---
+
+### How to Present Impact
+
+**For Fast Mode (Quick Overview):**
+```
+✨ **What I improved:**
+
+🎯 Made your goal clearer - AI will know exactly what you want
+📋 Added missing tech details - Framework, database, API format
+✅ Added success criteria - How to know when it's done
+
+Your prompt is ready!
+```
+
+**For Deep Mode (Detailed Breakdown):**
+```
+## Improvement Summary
+
+### High-Impact Changes (3)
+🎯 **Clarified the goal**
+   Before: "make a better search"
+   After: "build a search feature that returns relevant results in under 200ms"
+
+📋 **Added missing requirements**
+   - Tech stack: React + Node.js + Elasticsearch
+   - Data source: Product catalog API
+   - User context: Logged-in customers
+
+⚠️ **Identified edge cases**
+   - Empty search results
+   - Special characters in queries
+   - Very long queries (>200 chars)
+
+### Medium-Impact Changes (2)
+📐 **Reorganized structure**
+   Grouped related requirements together
+
+✅ **Added success criteria**
+   - Response time < 200ms
+   - Relevance score > 80%
+   - Works on mobile and desktop
+
+### Overall
+Your prompt went from **vague** to **production-ready**.
+```
+
+---
+
+### Mapping Patterns to Impact Descriptions
+
+When these patterns are applied, use these descriptions:
+
+| Pattern | Impact | User-Friendly Description |
+|---------|--------|--------------------------|
+| ObjectiveClarifier | 🎯 High | "Made your goal clearer" |
+| CompletenessValidator | 📋 High | "Added missing details" |
+| AmbiguityDetector | 🔍 High | "Fixed vague language" |
+| EdgeCaseIdentifier | ⚠️ High | "Spotted potential problems" |
+| ConcisenessFilter | ✂️ High | "Removed confusing parts" |
+| StructureOrganizer | 📐 Medium | "Better organization" |
+| ActionabilityEnhancer | 🎯 High | "Made it actionable" |
+| SuccessCriteriaEnforcer | ✅ Medium | "Added success criteria" |
+| TechnicalContextEnricher | 📊 Medium | "Added context" |
+| ScopeDefiner | 🔄 Medium | "Made it more specific" |
+| AlternativePhrasingGenerator | 💬 Light | "Offered alternatives" |
+| OutputFormatEnforcer | 🏷️ Medium | "Clearer output format" |
+
+---
+
+### When to Show Full vs Summary Impact
+
+**Show Full Impact When:**
+- Deep mode analysis
+- Quality improved significantly (>20% jump)
+- User asked "what did you change?"
+- Multiple high-impact changes made
+
+**Show Summary When:**
+- Fast mode (keep it quick)
+- Minor improvements only
+- User seems to want to move on
+- Quality was already good
+
+---
+
+### Example: Fast Mode Summary
+
+```
+✨ Your prompt is now better:
+
+🎯 Clearer goal - AI knows exactly what to build
+📋 Tech details added - Framework, database, hosting
+✅ Success criteria - How to know when it's done
+
+**Before:** 45/100 → **After:** 85/100
+
+Ready to use!
+```
+
+---
+
+### Example: Deep Mode Full Breakdown
+
+```
+## 📊 Improvement Analysis
+
+### What I Changed (7 improvements)
+
+**High Impact (3 changes):**
+1. 🎯 **Clarified the objective**
+   Your original: "build something for managing tasks"
+   Now: "build a task management API with CRUD operations, user assignment, and due date tracking"
+
+2. 📋 **Added missing technical requirements**
+   - Framework: Express.js
+   - Database: PostgreSQL
+   - Auth: JWT tokens
+   - API format: REST with JSON responses
+
+3. ⚠️ **Identified edge cases to handle**
+   - Task assigned to deleted user
+   - Past due dates
+   - Empty task lists
+   - Concurrent edits
+
+**Medium Impact (3 changes):**
+4. 📐 **Reorganized for clarity** - Grouped features logically
+5. ✅ **Added success criteria** - Response times, test coverage
+6. 🏷️ **Structured the output** - Clear sections for AI to follow
+
+**Light Polish (1 change):**
+7. 💬 **Smoothed wording** - Minor readability improvements
+
+### Quality Score
+| Dimension | Before | After |
+|-----------|--------|-------|
+| Clarity | 4/10 | 9/10 |
+| Completeness | 3/10 | 9/10 |
+| Actionability | 5/10 | 9/10 |
+
+**Your prompt went from 40% to 90% quality.**
+```
+
+---
+
+### Handling "No Changes Needed"
+
+Sometimes the prompt is already good:
+
+```
+✅ **Your prompt looks great!**
+
+I checked for common issues and your prompt:
+- Has a clear goal
+- Includes necessary details
+- Is well-organized
+
+No improvements needed - ready to use as-is!
+```

package/dist/templates/slash-commands/_components/sections/prd-examples.md

@@ -0,0 +1,289 @@
+## PRD Examples
+
+Real examples of mini-PRDs to help users understand what good planning looks like.
+
+---
+
+### Example 1: Simple Mobile App
+
+```markdown
+# Mini-PRD: Habit Tracker App
+
+## What We're Building
+A mobile app that helps people build good habits without the guilt.
+Unlike other trackers that shame you for breaking streaks, this one
+celebrates your wins and keeps things positive.
+
+## Who It's For
+- People who've tried habit apps but felt judged
+- Anyone who wants to build small daily habits
+- People who prefer encouragement over pressure
+
+## The Problem We're Solving
+Most habit trackers use streaks and "don't break the chain" psychology.
+When users miss a day, they feel like failures and often give up entirely.
+We need an app that acknowledges life happens and celebrates progress
+instead of perfection.
+
+## Must-Have Features (v1)
+1. **Add habits to track** - Simple creation with name and reminder time
+2. **Mark habits complete** - One tap to check off
+3. **Positive progress view** - "You've done this 15 times!" not "Day 3 of streak"
+4. **Gentle reminders** - Optional notifications, easy to snooze
+5. **Weekly celebration** - End-of-week summary highlighting wins
+
+## Nice-to-Have Features (Later)
+- Share progress with friends
+- Habit insights and patterns
+- Custom celebration messages
+- Dark mode
+
+## How We'll Know It's Working
+- Users can add a habit in under 10 seconds
+- App never shows negative language (no "streak broken")
+- 70% of users who try it stick around for 2+ weeks
+- Users report feeling "encouraged" in feedback
+
+## Technical Approach
+- React Native for iOS and Android
+- Local storage for data (no account required)
+- Simple, cheerful UI with soft colors
+- Push notifications via device native APIs
+
+## What's NOT In Scope
+- Social features (v1 is personal only)
+- Data export
+- Web version
+- Integrations with other apps
+```
+
+---
+
+### Example 2: API/Backend Service
+
+```markdown
+# Mini-PRD: User Management API
+
+## What We're Building
+A REST API for managing users in our web application. Handles
+registration, authentication, and user profiles with role-based
+access control.
+
+## Who It's For
+- Frontend developers building our web app
+- Admin team managing user accounts
+- Other services that need user data
+
+## The Problem We're Solving
+Our current auth is scattered across multiple files with no clear
+structure. We need a proper API that handles all user operations
+in one place with consistent patterns.
+
+## Must-Have Features (v1)
+1. **User registration** - Email + password, email verification
+2. **Authentication** - Login, logout, password reset
+3. **JWT tokens** - Access (15min) + refresh (7 days)
+4. **User profiles** - View and update own profile
+5. **Role-based access** - Admin, Editor, Viewer levels
+6. **Admin operations** - List users, change roles, disable accounts
+
+## Nice-to-Have Features (Later)
+- OAuth (Google, GitHub login)
+- Two-factor authentication
+- Audit logging
+- API rate limiting per user
+
+## How We'll Know It's Working
+- All endpoints respond in under 100ms
+- 100% test coverage on auth flows
+- Zero security vulnerabilities in penetration testing
+- Frontend team can integrate in under 1 day
+
+## Technical Approach
+- Node.js with Express framework
+- PostgreSQL database
+- JWT for auth tokens
+- bcrypt for password hashing
+- Jest for testing
+
+## API Endpoints Overview
+- POST /auth/register
+- POST /auth/login
+- POST /auth/logout
+- POST /auth/refresh
+- POST /auth/forgot-password
+- GET/PUT /users/me
+- GET /users (admin only)
+- PUT /users/:id/role (admin only)
+
+## What's NOT In Scope
+- Frontend UI for auth
+- Email service (will use existing)
+- User analytics
+- Multi-tenancy
+```
+
+---
+
+### Example 3: Feature Addition
+
+```markdown
+# Mini-PRD: Search Feature for E-commerce Site
+
+## What We're Building
+A search feature that lets customers find products quickly. Should
+be fast, relevant, and work well on mobile.
+
+## Who It's For
+- Customers shopping on our site
+- Especially mobile users (60% of our traffic)
+- People who know what they want and don't want to browse
+
+## The Problem We're Solving
+Customers are abandoning our site because they can't find products.
+Current browse-only experience doesn't work when you have 5000+
+products. We need search.
+
+## Must-Have Features (v1)
+1. **Search box** - Visible on every page, especially mobile
+2. **Instant results** - Show results as user types
+3. **Product cards** - Image, name, price in results
+4. **Filters** - Category, price range, in-stock only
+5. **No results page** - Helpful suggestions when search fails
+
+## Nice-to-Have Features (Later)
+- Search suggestions/autocomplete
+- Recent searches
+- "Did you mean?" for typos
+- Voice search on mobile
+
+## How We'll Know It's Working
+- Results appear in under 200ms
+- 80%+ of searches return relevant results
+- Conversion rate from search > browse
+- Mobile search usage > 30% of all searches
+
+## Technical Approach
+- Elasticsearch for search backend
+- React components for UI
+- Debounced search (300ms delay while typing)
+- Server-side filtering for performance
+
+## Integration Points
+- Product database (PostgreSQL)
+- Image CDN for product thumbnails
+- Analytics for search tracking
+
+## What's NOT In Scope
+- Personalized results (same results for everyone)
+- Search within categories (just global search)
+- Advanced operators ("AND", "OR", quotes)
+```
+
+---
+
+### Example 4: Internal Tool
+
+```markdown
+# Mini-PRD: Team Task Board
+
+## What We're Building
+A simple Kanban board for our team to track tasks. Think Trello
+but just for us, without all the features we don't use.
+
+## Who It's For
+- Our development team (8 people)
+- Project manager for oversight
+- Occasionally stakeholders for status updates
+
+## The Problem We're Solving
+We're paying for Trello but only use 10% of it. Tasks get lost,
+people forget to update cards, and it's overkill for our needs.
+We want something simpler that fits how we actually work.
+
+## Must-Have Features (v1)
+1. **Three columns** - To Do, In Progress, Done
+2. **Task cards** - Title, description, assignee
+3. **Drag and drop** - Move cards between columns
+4. **Comments** - Discuss tasks without leaving the board
+5. **Slack notifications** - When tasks move or get assigned
+
+## Nice-to-Have Features (Later)
+- Due dates with reminders
+- Labels/tags
+- Multiple boards per project
+- Time tracking
+
+## How We'll Know It's Working
+- Team adopts it within 1 week
+- No tasks "fall through the cracks"
+- Status meetings take 50% less time
+- Nobody asks "what are you working on?"
+
+## Technical Approach
+- React frontend
+- Node.js backend
+- MongoDB for flexibility
+- Socket.io for real-time updates
+- Slack API integration
+
+## What's NOT In Scope
+- Mobile app (desktop only for now)
+- Reporting/analytics
+- Time tracking
+- Multiple teams/permissions
+```
+
+---
+
+### PRD Template (Blank)
+
+Copy and fill in:
+
+```markdown
+# Mini-PRD: [Project Name]
+
+## What We're Building
+[1-2 sentences describing the product/feature]
+
+## Who It's For
+- [Primary user type]
+- [Secondary user type]
+- [Use case context]
+
+## The Problem We're Solving
+[What's the pain point? Why does this need to exist?]
+
+## Must-Have Features (v1)
+1. **[Feature]** - [Brief description]
+2. **[Feature]** - [Brief description]
+3. **[Feature]** - [Brief description]
+
+## Nice-to-Have Features (Later)
+- [Feature]
+- [Feature]
+
+## How We'll Know It's Working
+- [Measurable success criteria]
+- [Measurable success criteria]
+- [Measurable success criteria]
+
+## Technical Approach
+- [Key technology choices]
+- [Architecture notes]
+
+## What's NOT In Scope
+- [Explicitly excluded feature]
+- [Explicitly excluded feature]
+```
+
+---
+
+### Key Elements of a Good Mini-PRD
+
+1. **Clear problem statement** - Why are we building this?
+2. **Specific users** - Who exactly will use it?
+3. **Prioritized features** - What's essential vs nice-to-have?
+4. **Success metrics** - How do we measure success?
+5. **Technical direction** - Enough detail to start, not over-specified
+6. **Explicit scope** - What we're NOT doing is as important as what we are

package/dist/templates/slash-commands/_components/troubleshooting/vibecoder-recovery.md

@@ -0,0 +1,223 @@
+## Recovery Patterns for Vibecoders
+
+When something goes wrong, help users gracefully. Always try to fix it yourself first.
+
+---
+
+### Prompt Save Issues
+
+#### Can't Save Prompt
+**What happened:** Failed to save the improved prompt to disk
+**You try first:**
+1. Create the missing directory: `mkdir -p .clavix/outputs/prompts/fast`
+2. Retry the save operation
+
+**If still fails, say:**
+> "I had trouble saving your prompt, but no worries - here's your improved version.
+> You can copy it and I'll try saving again next time:
+>
+> [Show the improved prompt]"
+
+#### Prompt Not Found
+**What happened:** User asked about a prompt that doesn't exist
+**You try first:**
+1. Run `clavix prompts list` to see what's available
+2. Check if there's a similar prompt ID
+
+**Say:**
+> "I can't find that prompt. Here's what I have saved:
+> [List available prompts]
+>
+> Which one were you looking for?"
+
+---
+
+### Task Issues
+
+#### Task Not Found
+**What happened:** Tried to complete a task that doesn't exist
+**You try first:**
+1. Run `clavix implement --list` to get current tasks
+2. Check for typos in task ID
+
+**Say:**
+> "I can't find that task. Let me show you the available tasks:
+> [List tasks]
+>
+> Which one did you mean?"
+
+#### Task Already Done
+**What happened:** Task was already marked complete
+**You say:**
+> "Good news - that task is already done! Here's what's left:
+> [Show remaining tasks]"
+
+#### Wrong Task Order
+**What happened:** User wants to skip ahead or go back
+**You say:**
+> "I'd recommend doing the tasks in order since [task X] depends on [task Y].
+> Want me to:
+> 1. Continue with the current task
+> 2. Skip ahead anyway (might cause issues)"
+
+---
+
+### Project Issues
+
+#### No PRD Found
+**What happened:** Tried to plan tasks but no PRD exists
+**You say:**
+> "I don't see a plan for this project yet.
+> Want me to help you create one? Just describe what you're building
+> and I'll put together a proper plan."
+
+#### Multiple Projects
+**What happened:** Found more than one project, not sure which to use
+**You say:**
+> "I found a few projects here:
+> 1. **todo-app** - 3 tasks done, 2 remaining
+> 2. **auth-feature** - Not started yet
+>
+> Which one should we work on?"
+
+#### Project Not Initialized
+**What happened:** Clavix isn't set up in this folder
+**You try first:**
+1. Run `clavix init` to set up automatically
+
+**Say:**
+> "Let me set up Clavix for this project real quick...
+> [After init completes]
+> All set! Now, what would you like to do?"
+
+---
+
+### Verification Issues
+
+#### Tests Failing
+**What happened:** Automated verification found failing tests
+**You say:**
+> "Some tests didn't pass. Here's what I found:
+>
+> ❌ **[Test name]** - [Brief explanation]
+>
+> Would you like me to:
+> 1. Try to fix these issues
+> 2. Show you more details about what failed
+> 3. Skip verification for now (not recommended)"
+
+#### Can't Run Verification
+**What happened:** Verification hooks couldn't run
+**You try first:**
+1. Check if package.json exists
+2. Check for npm/yarn/pnpm lock files
+
+**Say:**
+> "I couldn't run the automatic checks. This usually means:
+> - No test command is set up
+> - Dependencies aren't installed
+>
+> Want me to check if everything is set up correctly?"
+
+#### Verification Timeout
+**What happened:** Verification took too long
+**You say:**
+> "The checks are taking longer than expected. This might be a big test suite.
+> Want me to:
+> 1. Keep waiting
+> 2. Cancel and mark for manual verification"
+
+---
+
+### File System Issues
+
+#### Permission Denied
+**What happened:** Can't write to a file or directory
+**You say:**
+> "I don't have permission to write to that location.
+> This is usually a folder permissions issue.
+>
+> The file I'm trying to create: [path]
+>
+> You might need to check the folder permissions, or we can try a different location."
+
+#### Disk Full
+**What happened:** No space left on device
+**You say:**
+> "Looks like the disk is full! I can't save anything right now.
+>
+> Once you free up some space, we can continue where we left off."
+
+#### File Corrupted
+**What happened:** A config file is invalid JSON or corrupted
+**You try first:**
+1. Check if it's a simple syntax error
+2. Try to recover valid data
+
+**If can't recover, say:**
+> "One of the config files got corrupted. I can:
+> 1. Start fresh (you'll lose saved settings)
+> 2. Show you the file so you can try to fix it manually
+>
+> What would you prefer?"
+
+---
+
+### Git Issues
+
+#### Not a Git Repository
+**What happened:** Git commands fail because no repo exists
+**You say:**
+> "This folder isn't set up with Git yet.
+> Want me to initialize it? This will let me track your changes."
+
+#### Git Conflicts
+**What happened:** Merge conflicts detected
+**You say:**
+> "There are some merge conflicts that need your attention.
+> I can't automatically resolve these because they need human judgment.
+>
+> Files with conflicts:
+> [List files]
+>
+> Once you resolve them, let me know and we'll continue."
+
+#### Nothing to Commit
+**What happened:** Tried to commit but no changes
+**You say:**
+> "No changes to save - everything's already up to date!"
+
+---
+
+### Network Issues
+
+#### Timeout
+**What happened:** Network request timed out
+**You try first:**
+1. Retry the request once
+
+**If still fails, say:**
+> "Having trouble connecting. This might be a temporary network issue.
+> Want me to try again, or should we continue without this?"
+
+---
+
+### General Recovery Protocol
+
+For ANY unexpected error:
+
+1. **Don't panic the user** - Stay calm, be helpful
+2. **Explain simply** - No technical jargon
+3. **Offer options** - Give 2-3 clear choices
+4. **Preserve their work** - Never lose user's content
+5. **Provide a path forward** - Always suggest next steps
+
+**Template:**
+> "Hmm, something unexpected happened. [Brief, friendly explanation]
+>
+> Don't worry - your work is safe. Here's what we can do:
+> 1. [Option A - usually try again]
+> 2. [Option B - alternative approach]
+> 3. [Option C - skip for now]
+>
+> What sounds good?"