seo/META_DESCRIPTION_GUIDE.md

# Meta Description Generation Guide

AI-powered meta description generation and optimization for WordPress posts.

## Overview

The meta description generator uses AI to create SEO-optimized meta descriptions for your blog posts. It can:

- **Generate new meta descriptions** for posts without them
- **Improve existing meta descriptions** that are poor quality
- **Optimize length** (120-160 characters - ideal for SEO)
- **Include focus keywords** naturally
- **Add call-to-action** elements when appropriate

## Usage

### Generate for All Posts

```bash
# Generate meta descriptions for all posts
./seo meta_description

# Use a specific CSV file
./seo meta_description output/all_posts_2026-02-16.csv
```

### Generate Only for Missing Meta Descriptions

```bash
# Only generate for posts without meta descriptions
./seo meta_description --only-missing
```

### Improve Poor Quality Meta Descriptions

```bash
# Only regenerate meta descriptions with poor quality scores
./seo meta_description --only-poor

# Limit to first 10 poor quality meta descriptions
./seo meta_description --only-poor --limit 10
```

### Dry Run Mode

Preview what would be processed:

```bash
./seo meta_description --dry-run
./seo meta_description --dry-run --only-missing
```

## Command Options

| Option | Description |
|--------|-------------|
| `--only-missing` | Only generate for posts without meta descriptions |
| `--only-poor` | Only generate for posts with poor quality meta descriptions |
| `--limit <N>` | Limit number of posts to process |
| `--output`, `-o` | Custom output file path |
| `--dry-run` | Preview without generating |
| `--verbose`, `-v` | Enable verbose logging |

## How It Works

### 1. Content Analysis

The AI analyzes:
- Post title
- Content preview (first 500 characters)
- Excerpt (if available)
- Focus keyword (if specified)
- Current meta description (if exists)

### 2. AI Generation

The AI generates meta descriptions following SEO best practices:
- **Length**: 120-160 characters (optimal for search engines)
- **Keywords**: Naturally includes focus keyword
- **Compelling**: Action-oriented and engaging
- **Accurate**: Clearly describes post content
- **Active voice**: Uses active rather than passive voice
- **Call-to-action**: Includes CTA when appropriate

### 3. Quality Validation

Each generated meta description is scored on:
- **Length optimization** (120-160 chars = 100 points)
- **Proper ending** (period = +5 points)
- **Call-to-action words** (+5 points)
- **Overall quality** (minimum 70 points to pass)

### 4. Output

Results are saved to CSV with:
- Original meta description
- Generated meta description
- Length of generated meta
- Validation score (0-100)
- Whether length is optimal
- Whether it's an improvement

## Output Format

The tool generates a CSV file in `output/`:

```
output/meta_descriptions_20260216_143022.csv
```

### CSV Columns

| Column | Description |
|--------|-------------|
| `post_id` | WordPress post ID |
| `site` | Site name |
| `title` | Post title |
| `current_meta_description` | Existing meta (if any) |
| `generated_meta_description` | AI-generated meta |
| `generated_length` | Character count |
| `validation_score` | Quality score (0-100) |
| `is_optimal_length` | True if 120-160 chars |
| `improvement` | True if better than current |
| `status` | Generation status |

## Examples

### Example 1: Generate All Missing Meta Descriptions

```bash
# Export posts first
./seo export

# Generate meta descriptions for posts without them
./seo meta_description --only-missing
```

**Output:**
```
Generating AI-optimized meta descriptions...
  Filter: Only posts without meta descriptions
Processing post 1/45
✓ Generated meta description (score: 95, length: 155)
...

✅ Meta description generation completed!
  Results: output/meta_descriptions_20260216_143022.csv

📊 Summary:
  Total processed: 45
  Improved: 42 (93.3%)
  Optimal length: 40 (88.9%)
  Average score: 92.5
  API calls: 45
```

### Example 2: Fix Poor Quality Meta Descriptions

```bash
# Only improve meta descriptions scoring below 70
./seo meta_description --only-poor --limit 20
```

### Example 3: Test with Small Batch

```bash
# Test with first 5 posts
./seo meta_description --limit 5
```

### Example 4: Custom Output File

```bash
./seo meta_description --output output/custom_meta_gen.csv
```

## Meta Description Quality Scoring

### Scoring Criteria

| Criteria | Points |
|----------|--------|
| Optimal length (120-160 chars) | 100 |
| Too short (< 120 chars) | 50 - (deficit) |
| Too long (> 160 chars) | 50 - (excess) |
| Ends with period | +5 |
| Contains CTA words | +5 |

### Quality Thresholds

- **Excellent (90-100)**: Ready to use
- **Good (70-89)**: Minor improvements possible
- **Poor (< 70)**: Needs regeneration

### CTA Words Detected

The system looks for action words like:
- learn, discover, find, explore
- read, get, see, try, start
- and more...

## Best Practices

### Before Generation

1. **Export fresh data** - Ensure you have latest posts
   ```bash
   ./seo export
   ```

2. **Review focus keywords** - Posts with focus keywords get better results

3. **Test with small batch** - Try with `--limit 5` first

### During Generation

1. **Monitor scores** - Watch validation scores in real-time
2. **Check API usage** - Track number of API calls
3. **Use filters** - Target only what needs improvement

### After Generation

1. **Review results** - Open the CSV and check generated metas
2. **Manual approval** - Don't auto-publish; review first
3. **A/B test** - Compare performance of new vs old metas

## Integration with WordPress

### Manual Update

1. Open the generated CSV: `output/meta_descriptions_*.csv`
2. Copy generated meta descriptions
3. Update in WordPress SEO plugin (RankMath, Yoast, etc.)

### Automated Update (Future)

Future versions may support direct WordPress updates:
```bash
# Not yet implemented
./seo meta_description --apply-to-wordpress
```

## API Usage & Cost

### API Calls

- Each post requires 1 API call
- Rate limited to 2 calls/second (0.5s delay)
- Uses Claude AI via OpenRouter

### Estimated Cost

Approximate cost per 1000 meta descriptions:
- **~$0.50 - $2.00** depending on content length
- Check OpenRouter pricing for current rates

### Monitoring

The summary shows:
- Total API calls made
- Cost tracking (if enabled)

## Troubleshooting

### No Posts to Process

**Problem:** "No posts to process"

**Solutions:**
1. Export posts first: `./seo export`
2. Check CSV has required columns
3. Verify filter isn't too restrictive

### Low Quality Scores

**Problem:** Generated metas scoring below 70

**Solutions:**
1. Add focus keywords to posts
2. Provide better content previews
3. Try regenerating with different parameters

### API Errors

**Problem:** "API call failed"

**Solutions:**
1. Check internet connection
2. Verify API key in `.env`
3. Check OpenRouter account status
4. Reduce batch size with `--limit`

### Rate Limiting

**Problem:** Too many API calls

**Solutions:**
1. Use `--limit` to batch process
2. Wait between batches
3. Upgrade API plan if needed

## Comparison with Other Tools

| Feature | This Tool | Other SEO Tools |
|---------|-----------|-----------------|
| AI-powered | ✅ Yes | ⚠️ Sometimes |
| Batch processing | ✅ Yes | ✅ Yes |
| Quality scoring | ✅ Yes | ❌ No |
| Custom prompts | ✅ Yes | ❌ No |
| WordPress integration | ⚠️ Manual | ✅ Some |
| Cost | Pay-per-use | Monthly subscription |

## Related Commands

- `seo export` - Export posts for analysis
- `seo analyze` - AI analysis with recommendations
- `seo seo_check` - SEO quality checking

## See Also

- [README.md](README.md) - Main documentation
- [ENHANCED_ANALYSIS_GUIDE.md](ENHANCED_ANALYSIS_GUIDE.md) - AI analysis guide
- [EDITORIAL_STRATEGY_GUIDE.md](EDITORIAL_STRATEGY_GUIDE.md) - Content strategy

---

**Made with ❤️ for better SEO automation**