seo/ENHANCED_ANALYSIS_GUIDE.md

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

# Analyze all fields (default behavior)
./seo analyze

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

Selective Field Analysis

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# Analyze meta descriptions, save to specific file
./seo analyze -f meta_description -o output/meta_analysis.csv

Workflow Examples

Workflow 1: SEO Title Optimization

# 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

# 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

# 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

# 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

# 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

# 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

# Error: OPENROUTER_API_KEY not set
# Solution: Add to .env file
echo "OPENROUTER_API_KEY=your_key_here" >> .env

High API Costs

# 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