vibn-frontend/lib/ai/prompts/README.md

# Prompt Management System

This directory contains all versioned system prompts for Vibn's chat modes.

## 📁 Structure

```
prompts/
├── index.ts                    # Exports all prompts
├── shared.ts                   # Shared prompt components
├── collector.ts                # Collector mode prompts
├── extraction-review.ts        # Extraction review mode prompts
├── vision.ts                   # Vision mode prompts
├── mvp.ts                      # MVP mode prompts
├── marketing.ts                # Marketing mode prompts
└── general-chat.ts             # General chat mode prompts
```

## 🔄 Versioning

Each prompt file contains:
1. **Version history** - All versions of the prompt
2. **Metadata** - Version number, date, description
3. **Current version** - Which version is active

### Example Structure

```typescript
const COLLECTOR_V1: PromptVersion = {
  version: 'v1',
  createdAt: '2024-11-17',
  description: 'Initial version',
  prompt: `...`,
};

const COLLECTOR_V2: PromptVersion = {
  version: 'v2',
  createdAt: '2024-12-01',
  description: 'Added context-aware chunking',
  prompt: `...`,
};

export const collectorPrompts = {
  v1: COLLECTOR_V1,
  v2: COLLECTOR_V2,
  current: 'v2',  // ← Active version
};
```

## 📝 How to Add a New Prompt Version

1. **Open the relevant mode file** (e.g., `collector.ts`)
2. **Create a new version constant:**
   ```typescript
   const COLLECTOR_V2: PromptVersion = {
     version: 'v2',
     createdAt: '2024-12-01',
     description: 'What changed in this version',
     prompt: `
       Your new prompt text here...
     `,
   };
   ```
3. **Add to the prompts object:**
   ```typescript
   export const collectorPrompts = {
     v1: COLLECTOR_V1,
     v2: COLLECTOR_V2,  // Add new version
     current: 'v2',     // Update current
   };
   ```
4. **Done!** The system will automatically use the new version.

## 🔙 How to Rollback

Simply change the `current` field:

```typescript
export const collectorPrompts = {
  v1: COLLECTOR_V1,
  v2: COLLECTOR_V2,
  current: 'v1',  // Rolled back to v1
};
```

## 📊 Benefits of This System

1. **Version History** - Keep all previous prompts for reference
2. **Easy Rollback** - Instantly revert to a previous version
3. **Git-Friendly** - Clear diffs show exactly what changed
4. **Documentation** - Each version has a description of changes
5. **A/B Testing Ready** - Can easily test multiple versions
6. **Isolated Changes** - Changing one prompt doesn't affect others

## 🎯 Usage in Code

```typescript
// Import current prompts (most common)
import { MODE_SYSTEM_PROMPTS } from '@/lib/ai/chat-modes';

const prompt = MODE_SYSTEM_PROMPTS['collector_mode'];

// Or access version history
import { collectorPrompts } from '@/lib/ai/prompts';

console.log(collectorPrompts.v1.prompt);  // Old version
console.log(collectorPrompts.current);     // 'v2'
```

## 🚀 Future Enhancements

### Analytics Tracking
Track performance by prompt version:
```typescript
await logPromptUsage({
  mode: 'collector_mode',
  version: collectorPrompts.current,
  userId: user.id,
  responseQuality: 0.85,
});
```

### A/B Testing
Test multiple versions simultaneously:
```typescript
const promptVersion = userInExperiment ? 'v2' : 'v1';
const prompt = collectorPrompts[promptVersion].prompt;
```

### Database Storage
Move to Firestore for dynamic updates:
```typescript
// Future: Load from database
const prompt = await getPrompt('collector_mode', 'latest');
```

## 📚 Best Practices

1. **Always add a description** - Future you will thank you
2. **Never delete old versions** - Keep history for rollback
3. **Test before deploying** - Ensure new prompts work as expected
4. **Document changes** - What problem does the new version solve?
5. **Version incrementally** - Don't skip version numbers

## 🔍 Example: Adding Context-Aware Chunking

```typescript
// 1. Create new version
const COLLECTOR_V2: PromptVersion = {
  version: 'v2',
  createdAt: '2024-11-17',
  description: 'Added instructions for context-aware chunking',
  prompt: `
${COLLECTOR_V1.prompt}

**Context-Aware Retrieval**:
When referencing retrieved chunks, always cite the source document
and chunk number for transparency.
  `,
};

// 2. Update prompts object
export const collectorPrompts = {
  v1: COLLECTOR_V1,
  v2: COLLECTOR_V2,
  current: 'v2',
};

// 3. Deploy and monitor
// If issues arise, simply change current: 'v1' to rollback
```

---

**Questions?** Check the code in any prompt file for examples.