content-optimization

What this skill does

# Content Optimization Skill

## Purpose

Systematically enhance any type of content using research-backed techniques and best practices. This skill:
- Automatically detects content type
- Applies domain-specific optimization techniques
- Provides step-by-step approval workflow (especially for prompts)
- Measures improvement with confidence scores
- Supports multiple optimization modes (conservative, moderate, aggressive)

## When to Use

- **AI Prompts**: Improve clarity, add reasoning chains, optimize for better responses
- **Code**: Refactor for performance, readability, error handling
- **Database Queries**: Optimize performance, suggest indexes, enable caching
- **Commit Messages**: Clarify intent, follow conventional format
- **Documentation**: Improve structure, add examples, enhance clarity
- **Communication**: Refine tone, improve call-to-action, enhance effectiveness

## The Problem

Without systematic optimization:
- Prompts to AI models are vague, leading to poor responses
- Code is written without considering performance
- Database queries are inefficient, causing slowdowns
- Commit messages lack clarity about changes
- Documentation is unclear for readers
- Communications miss the mark

With this skill:
- Prompts generate 45-115% better responses (research-backed)
- Code is performant and maintainable
- Queries execute faster with proper indexes
- Commit history is clear and navigable
- Documentation is clear and helpful
- Communications are more effective

## Supported Content Types

| Type | Purpose | Techniques |
|------|---------|-----------|
| `prompt` | AI prompt optimization | Expert personas, step-by-step reasoning, stakes language, challenge framing |
| `code` | Source code improvement | Performance, readability, error handling, best practices |
| `query` | Database/search query | Indexes, execution plans, caching, pagination |
| `commit` | Git commit messages | Conventional commits, clarity, intent description |
| `docs` | Documentation | Structure, examples, clarity, accessibility |
| `email` | Communication | Tone, clarity, call-to-action, effectiveness |

## Prompt Optimization Techniques

### 1. Expert Persona Assignment
Assigns detailed expert role with relevant background.
```
Instead of: "Help me debug this"
Optimized: "As a senior backend engineer with 10 years of experience debugging distributed systems..."
```
**Impact**: +60% accuracy (Kong et al., 2023)

### 2. Step-by-Step Reasoning
Instructs systematic analysis approach.
```
"Take a deep breath and think step by step. First, identify the symptoms..."
```
**Impact**: +46% accuracy (Yang et al., 2023)

### 3. Stakes Language
Frames importance and consequences.
```
"This is critical for production. Incorrect analysis could cause service outage."
```
**Impact**: +45% quality (Bsharat et al., 2023)

### 4. Challenge Framing
Positions as difficult problem worth solving.
```
"This is a tricky optimization problem. I bet you can't find the perfect balance."
```
**Impact**: +115% on hard tasks (Li et al., 2023)

### 5. Self-Evaluation
Requests confidence ratings and uncertainty identification.
```
"Rate your confidence in this solution (0.0-1.0) and identify any uncertainties."
```
**Impact**: +10% calibration

## Usage Examples

### Optimize AI Prompts
```bash
/optimize "Help me debug auth" --prompt
# Interactive approval workflow:
# - Shows detected domain (security)
# - Suggests optimization steps
# - Asks approve/reject/modify for each step
# - Calculates expected improvement

/optimize "Help me debug auth" --prompt --verbose
# Detailed walkthrough with reasoning for each optimization

/optimize "Help me debug auth" --prompt --mode=aggressive
# Apply maximum optimization (more aggressive than default)

/optimize "Help me debug auth" --prompt --mode=conservative
# Minimal changes, preserve original intent

# Skip optimization
/optimize "! Help me debug auth" --prompt
# Exclamation mark prefix bypasses optimization
```

### Optimize Source Code
```bash
/optimize src/auth.js --code
# Suggests: performance improvements, readability, error handling

/optimize src/auth.js --code --preview
# Show changes before applying

/optimize src/auth.js --code --apply
# Automatically apply optimizations

/optimize src/auth.js --code --mode=aggressive
# Maximum optimization (may add complexity)
```

### Optimize Database Queries
```bash
/optimize "SELECT * FROM users WHERE status = 'active'" --query
# Suggests: add indexes, pagination, caching, execution plan

/optimize "SELECT * FROM users WHERE status = 'active'" --query --preview
# Preview query optimization without applying
```

### Optimize Commit Messages
```bash
/optimize "fix: resolve login bug" --commit
# Suggests: add scope, detail, follow conventional commits

/optimize "fix: resolve login bug" --commit --apply
# Apply optimized message
```

### Optimize Documentation
```bash
/optimize "README.md" --docs
# Suggests: structure improvements, add examples, clarify sections

/optimize "README.md" --docs --interactive
# Ask clarifying questions about audience and purpose
```

### Optimize Communication
```bash
/optimize "Hey, can you review my code?" --email
# Suggests: professional tone, clear request, timeline

/optimize "Hey, can you review my code?" --email --apply
# Apply professional version
```

### Auto-Detect Content Type
```bash
/optimize "help me optimize this database query"
# Automatically detects as prompt, applies optimization
# (Or specify --type if auto-detection fails)
```

## Options

| Option | Description | Values | Default |
|--------|-------------|--------|---------|
| `--type <type>` | Content type | prompt/code/query/commit/docs/email | auto |
| `--mode <mode>` | Optimization intensity | conservative/moderate/aggressive | moderate |
| `--preview` | Show changes before applying | flag | false |
| `--apply` | Apply optimizations automatically | flag | false |
| `--interactive` | Ask clarifying questions | flag | false |
| `--verbose` | Show detailed process | flag | false |
| `--force` | Apply without confirmation | flag | false |
| `--output <file>` | Save to file instead of stdout | path | stdout |
| `--source <sources>` | Research sources | anthropic/openai/opencode/all | all |

## Interactive Approval Workflow (Prompts)

When optimizing prompts, you get step-by-step approval:

### Step 1: Analysis
```
Domain detected: Security (authentication/debugging)
Complexity: Medium (moderate ambiguity)
Suggested techniques:
  ✓ Expert Persona (security engineer with 10yr exp)
  ✓ Step-by-Step Reasoning (systematic debugging approach)
  ✓ Stakes Language (production impact)
  ✓ Self-Evaluation (confidence rating)
```

### Step 2: Approval
```
For each technique, choose:
  [A] Approve     - Use this technique
  [R] Reject      - Skip this technique
  [M] Modify      - Change the wording
  [E] Edit        - Full edit mode
  [C] Cancel      - Don't optimize
```

### Step 3: Result
```
Original: "Help me debug auth"

Optimized: "As a senior security engineer with 10 years of experience 
debugging distributed authentication systems, help me systematically 
debug this login issue. This is production-critical - incorrect analysis 
could cause service outage. Walk through your reasoning step by step. 
Rate your confidence (0.0-1.0) and identify any uncertainties."

Expected improvement: +78% response quality
Confidence: 0.92
```

## Code Optimization Techniques

- **Performance**: Reduce complexity, optimize algorithms, cache results
- **Readability**: Better variable names, extract functions, add comments
- **Error Handling**: Add try-catch, validate inputs, handle edge cases
- **Best Practices**: Follow language conventions, use idioms, avoid antipatterns

## Query Optimization Techniques

- **Indexes**: Suggest missing indexes on WHERE/JOIN columns
- **Execution Plans**: Show query plan analysis and bottlenecks
- **Pagination**: Add LIMIT/OFFSET for large result sets
- **Caching**: Identify cacheable queries
- **Join