# Ahrefs CSV Processing - Recurring Workflow Guide

**Last Updated:** 2026-01-27

## Quick Start (For Future Imports)

When you receive a new Ahrefs CSV export, run:

```bash
cd /Users/hadyelhady/Documents/GitHub/landingpage
python3 v2/scripts/blog/process-ahrefs-csv.py /path/to/new-ahrefs-export.csv
```

The script handles everything automatically:
1. Analyzes all opportunities
2. Validates against existing links and safety rules
3. Generates analysis report
4. Runs dry-run preview
5. Prompts for approval
6. Implements approved links

## Complete Workflow

### Step 1: Run the Workflow Script

```bash
python3 v2/scripts/blog/process-ahrefs-csv.py /path/to/ahrefs-export.csv
```

### Step 2: Review Analysis Report

The script generates:
- `v2/scripts/blog/ahrefs-analysis/analysis-report-{timestamp}.md`
- Shows breakdown: APPROVED / REJECTED / REVIEW
- Lists rejection reasons

### Step 3: Review Dry-Run Results

The script automatically runs a dry-run showing:
- Which links would be added
- Which files would be modified
- No files are actually changed

### Step 4: Approve Implementation

When prompted:
- Type `yes` to implement approved links
- Type `no` to skip (can run again later)

### Step 5: Verify Implementation

After implementation:
- Check `implementation-results-enhanced.json`
- Review backups in `ahrefs-analysis/backups/`
- Validate links on staging/production

## Options

### Auto-Approve (Skip Confirmation)

```bash
python3 v2/scripts/blog/process-ahrefs-csv.py /path/to/csv.csv --auto-approve
```

Use when:
- You've reviewed the analysis report
- You trust the automated validation
- You want to process multiple CSVs quickly

### Dry-Run Only (No Implementation)

```bash
python3 v2/scripts/blog/process-ahrefs-csv.py /path/to/csv.csv --dry-run-only
```

Use when:
- You only want to see what would happen
- You're reviewing before implementing
- You want to share results before implementing

## Understanding the Results

### Analysis Report Structure

```
## Summary
- APPROVED: X (Y%)
- REJECTED: Z (W%)
- REVIEW: A (B%)

## Rejection Reasons
- Link already exists: N
- Unsafe placement: M
- ...

## Detailed Results
[One section per opportunity with full details]
```

### Common Scenarios

**High Approval Rate (>30%):**
- Content needs more internal links
- Many new opportunities
- Good keyword coverage

**Low Approval Rate (<20%):**
- Content already well-linked (good!)
- Many duplicates (expected)
- Keywords in headers (consider expanding content)

**Many "Unsafe Placement" Rejections:**
- Keywords appear only in headers
- Consider expanding content paragraphs
- Or finding alternative keyword placements

## Safety Features

All processing includes:

- ✅ **Automatic Backups** - Every file backed up before modification
- ✅ **Dry-Run Default** - Always previews before implementing
- ✅ **Safe Placement Validation** - Never adds links to headers, FAQ questions
- ✅ **Duplicate Checking** - Prevents duplicate links
- ✅ **German Word Boundaries** - Respects German language rules
- ✅ **Comprehensive Logging** - Full audit trail

## File Locations

### Scripts
- `v2/scripts/blog/process-ahrefs-csv.py` - Main workflow script
- `v2/scripts/blog/analyze-ahrefs-opportunities-jan-2026.py` - Analysis engine
- `v2/scripts/blog/add-ahrefs-links-enhanced.py` - Implementation engine

### Output Files
All saved to: `v2/scripts/blog/ahrefs-analysis/`

- `analysis-report-{timestamp}.md` - Analysis report
- `analysis-results-{timestamp}.json` - Detailed JSON results
- `filtered-opportunities-enhanced.json` - Approved opportunities
- `implementation-results-enhanced.json` - Implementation results
- `backups/{slug}-{timestamp}.json` - Automatic backups
- `logs/implementation-{timestamp}.log` - Implementation logs

## Troubleshooting

### CSV File Not Found

```bash
# Use absolute path
python3 v2/scripts/blog/process-ahrefs-csv.py /absolute/path/to/csv.csv

# Or check file exists
ls -lh /path/to/csv.csv
```

### Analysis Fails

**Check CSV encoding:**
```bash
file /path/to/csv.csv
# Should show: UTF-16, little-endian
```

**Check CSV format:**
- Should be tab-separated (TSV)
- Should have header row
- Should contain: PR, Source page, Keyword, Target page, etc.

### No Approved Opportunities

This is normal and indicates:
- Content is already well-linked ✅
- Many opportunities are duplicates ✅
- Keywords are in headers (not linkable)

Review the analysis report to understand specific rejections.

### Implementation Fails

**Check:**
1. File permissions (should be writable)
2. JSON syntax (should be valid)
3. Backup directory exists
4. Log file for detailed errors: `ahrefs-analysis/logs/`

## Best Practices

### Before Each Import

1. ✅ **Backup your data** (automatic backups created, but good to have extra)
2. ✅ **Review CSV file** - Verify it's the latest export from Ahrefs
3. ✅ **Check file location** - Use absolute path or relative to project root

### After Each Import

1. ✅ **Review analysis report** - Understand why opportunities were rejected
2. ✅ **Check implementation results** - Verify links were added correctly
3. ✅ **Validate on staging** - Test links before production
4. ✅ **Monitor performance** - Track link performance in Google Search Console

### For Recurring Imports

1. ✅ **Use the workflow script** - Don't run scripts manually
2. ✅ **Review rejection patterns** - Learn what's already linked
3. ✅ **Track trends** - Note common rejection reasons over time
4. ✅ **Update content** - Consider expanding content if many opportunities rejected due to headers

## Example Workflow

```bash
# 1. Receive new CSV from Ahrefs
# File: ~/Desktop/Ordio/Internal Linking/2026/2. February/new-opportunities.csv

# 2. Run workflow
cd /Users/hadyelhady/Documents/GitHub/landingpage
python3 v2/scripts/blog/process-ahrefs-csv.py \
  ~/Desktop/Ordio/Internal\ Linking/2026/2.\ February/new-opportunities.csv

# 3. Review output
# Script shows:
# - Analysis summary
# - Dry-run results
# - Prompts for approval

# 4. Approve (type 'yes')
# Script implements approved links

# 5. Review results
cat v2/scripts/blog/ahrefs-analysis/implementation-results-enhanced.json
```

## Related Documentation

- `docs/seo/AHREFS_CSV_WORKFLOW.md` - Complete workflow guide
- `docs/seo/ahrefs-link-opportunities-process.md` - Detailed process documentation
- `v2/scripts/blog/QUICK_START_AHREFS.md` - Quick reference
- `v2/scripts/blog/ahrefs-analysis/WORKFLOW_SETUP.md` - Setup details

## Support

For questions or issues:
1. Check the analysis report for detailed reasons
2. Review implementation logs in `ahrefs-analysis/logs/`
3. Check backups if rollback needed
4. Review rejection patterns to understand trends