# Enhanced Analysis Guide

## Overview

The SEO automation tool now provides enhanced analysis capabilities with:

1. **Selective Field Analysis** - Choose which fields to analyze (title, meta description, categories, site)
2. **In-place CSV Updates** - Update input CSV with new columns (with automatic backup)
3. **Category Proposer** - Dedicated command for AI-powered category suggestions

## Commands

### 1. Enhanced Analysis (`seo analyze`)

Analyze posts with AI and add recommendation columns to your CSV.

#### Basic Usage
```bash
# Analyze all fields (default behavior)
./seo analyze

# Analyze specific CSV file
./seo analyze output/all_posts_2026-02-16.csv
```

#### Selective Field Analysis
```bash
# Analyze only titles
./seo analyze -f title

# Analyze titles and categories
./seo analyze -f title categories

# Analyze meta descriptions only
./seo analyze -f meta_description

# Analyze all fields
./seo analyze -f title meta_description categories site
```

#### Update Input CSV (In-place)
```bash
# Update input CSV with new columns (creates backup automatically)
./seo analyze -u

# Update with specific fields only
./seo analyze -u -f title meta_description

# Specify custom output file
./seo analyze -o output/my_analysis.csv
```

#### Output Columns

Depending on selected fields, the following columns are added:

**Title Analysis:**
- `proposed_title` - AI-suggested improved title
- `title_reason` - Explanation for title change

**Meta Description Analysis:**
- `proposed_meta_description` - AI-suggested meta description (120-160 chars)
- `meta_reason` - Explanation for meta description change

**Category Analysis:**
- `proposed_category` - AI-suggested best category
- `category_reason` - Explanation for category choice

**Site Analysis:**
- `proposed_site` - AI-suggested best site
- `site_reason` - Explanation for site recommendation

**Common Fields:**
- `ai_confidence` - AI confidence level (High/Medium/Low)
- `ai_priority` - Priority level (High/Medium/Low)

### 2. Category Proposer (`seo category_propose`)

Dedicated command for AI-powered category suggestions based on post content.

#### Usage
```bash
# Propose categories for latest export
./seo category_propose

# Propose categories for specific CSV
./seo category_propose output/all_posts_2026-02-16.csv

# Save to custom output file
./seo category_propose -o output/my_category_proposals.csv
```

#### Output Columns
- `post_id` - Post identifier
- `title` - Post title
- `current_categories` - Current categories
- `proposed_category` - AI-suggested category
- `alternative_categories` - Alternative category suggestions
- `category_reason` - Explanation for suggestion
- `category_confidence` - Confidence level

## Examples

### Example 1: Analyze Titles Only
```bash
# Analyze only titles for SEO optimization
./seo analyze -f title

# Output: analyzed_posts_YYYYMMDD_HHMMSS.csv
# Contains: original columns + proposed_title + title_reason + ai_confidence
```

### Example 2: Update CSV with Meta Descriptions
```bash
# Update input CSV with proposed meta descriptions
./seo analyze -u -f meta_description

# Creates:
# - all_posts_2026-02-16_backup_YYYYMMDD_HHMMSS.csv (backup)
# - all_posts_2026-02-16.csv (updated with new columns)
```

### Example 3: Full Category Analysis
```bash
# Propose categories for all posts
./seo category_propose

# Review proposals
open output/category_proposals_*.csv

# Apply approved categories manually in WordPress
```

### Example 4: Multi-Field Analysis
```bash
# Analyze titles and categories together
./seo analyze -f title categories

# Output includes:
# - proposed_title, title_reason
# - proposed_category, category_reason
# - ai_confidence, ai_priority
```

### Example 5: Targeted Analysis with Output
```bash
# Analyze meta descriptions, save to specific file
./seo analyze -f meta_description -o output/meta_analysis.csv
```

## Workflow Examples

### Workflow 1: SEO Title Optimization
```bash
# 1. Export posts
./seo export

# 2. Analyze titles only
./seo analyze -f title

# 3. Review proposed titles
open output/analyzed_posts_*.csv

# 4. Manually update best titles in WordPress
```

### Workflow 2: Category Reorganization
```bash
# 1. Export posts
./seo export

# 2. Get category proposals
./seo category_propose

# 3. Review proposals
open output/category_proposals_*.csv

# 4. Apply approved category changes
```

### Workflow 3: Complete SEO Audit
```bash
# 1. Export posts
./seo export

# 2. Analyze all fields
./seo analyze -f title meta_description categories site

# 3. Review comprehensive analysis
open output/analyzed_posts_*.csv

# 4. Implement changes based on AI recommendations
```

### Workflow 4: Incremental Analysis
```bash
# 1. Export posts
./seo export

# 2. Analyze titles (fast, low cost)
./seo analyze -f title

# 3. Later, analyze meta descriptions
./seo analyze -u -f meta_description

# 4. Later, analyze categories
./seo analyze -u -f categories

# Result: CSV progressively enriched with AI recommendations
```

## Cost Optimization

### Reduce API Costs

```bash
# Analyze only needed fields (saves tokens)
./seo analyze -f title  # Cheaper than analyzing all fields

# Use smaller batch sizes for better control
# (edit script or use environment variable)

# Analyze in stages
./seo analyze -f title
./seo analyze -u -f meta_description
# Total cost similar, but better control over each step
```

### Token Usage by Field

Approximate token usage per 100 posts:
- **title**: ~500 tokens (lowest cost)
- **meta_description**: ~800 tokens
- **categories**: ~600 tokens
- **site**: ~400 tokens (lowest cost)
- **All fields**: ~2000 tokens (best value)

## Best Practices

1. **Start Small**: Test with `-f title` first to see AI quality
2. **Review Before Applying**: Always review AI suggestions before implementing
3. **Use Backups**: The `-u` flag creates automatic backups
4. **Batch Analysis**: Analyze related fields together for better context
5. **Confidence Matters**: Pay attention to `ai_confidence` column
6. **Iterative Process**: Enrich CSVs incrementally for better control

## Troubleshooting

### No CSV File Found
```bash
# Error: No CSV file found
# Solution: Run export first or provide file path
./seo export
./seo analyze

# Or specify file directly
./seo analyze path/to/your/file.csv
```

### API Key Not Set
```bash
# Error: OPENROUTER_API_KEY not set
# Solution: Add to .env file
echo "OPENROUTER_API_KEY=your_key_here" >> .env
```

### High API Costs
```bash
# Reduce costs by analyzing fewer fields
./seo analyze -f title  # Instead of all fields

# Or analyze in batches
./seo analyze -f title
./seo analyze -u -f meta_description
```

## File Formats

### Input CSV Requirements

Must contain at minimum:
- `post_id` - Unique identifier
- `title` - Post title (for title analysis)
- `meta_description` - Current meta (for meta analysis)
- `categories` - Current categories (for category analysis)
- `site` - Current site (for site analysis)
- `content_preview` or `content` - Post content (recommended for all analyses)

### Output CSV Format

Standard output includes:
- All original columns
- New `proposed_*` columns for analyzed fields
- `*_reason` columns with explanations
- `ai_confidence` and `ai_priority` columns

---

**Version**: 1.0.0  
**Last Updated**: 2026-02-16  
**Related**: See ARCHITECTURE.md for system overview