# Blog Manual Review Troubleshooting Guide

**Last Updated:** 2026-01-11  
**Purpose:** Common issues and solutions for blog post manual review process

## Common Issues

### Issue 1: Manual Sections Missing After Regeneration

**Symptoms:**

- Manual sections disappeared after running regeneration script
- Content between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers is gone

**Solutions:**

1. **Check if safe regeneration was used:**

   ```bash
   php v2/scripts/blog/safe-regenerate-documentation.php --post={slug} --category={category} --backup
   ```

2. **Verify manual section markers are correct:**

   - Check for exact markers: `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->`
   - Ensure no typos or extra spaces
   - Check that markers are on separate lines

3. **Restore from backup:**

   ```bash
   # Check backup location
   ls v2/data/blog/regeneration-backups/

   # Restore manual sections
   php v2/scripts/blog/preserve-manual-edits.php --restore --backup={backup_path}
   ```

4. **Prevention:**
   - Always use `safe-regenerate-documentation.php` with `--backup` flag
   - Verify manual sections before regeneration
   - Test on one post first before batch processing

### Issue 2: Placeholders Not Populated

**Symptoms:**

- Placeholders like `{SEO_SCORE}` or `{REPORT_TIMESTAMP}` still present after regeneration
- Data files exist but placeholders not replaced

**Solutions:**

1. **Verify data files exist:**

   ```bash
   ls docs/content/blog/posts/{category}/{slug}/data/seo-analysis.json
   ```

2. **Check data file format:**

   ```bash
   cat docs/content/blog/posts/{category}/{slug}/data/seo-analysis.json | jq '.seo_score'
   ```

3. **Run auto-fill script:**

   ```bash
   php v2/scripts/blog/auto-fill-placeholders.php --post={slug} --category={category}
   ```

4. **Re-run data collection if needed:**
   ```bash
   php v2/scripts/blog/analyze-post-seo.php --post={slug} --category={category}
   php v2/scripts/blog/generate-post-documentation.php --post={slug} --category={category}
   ```

### Issue 3: Data Integration Incomplete

**Symptoms:**

- Search intent, SERP features, or competition data missing
- Documentation shows "To be identified" or similar placeholders

**Solutions:**

1. **Verify advanced data collection completed:**

   ```bash
   ls docs/content/blog/posts/{category}/{slug}/data/search-intent.json
   ls docs/content/blog/posts/{category}/{slug}/data/serp-features.json
   ls docs/content/blog/posts/{category}/{slug}/data/competition-levels.json
   ```

2. **Re-run advanced collection:**

   ```bash
   php v2/scripts/blog/run-all-advanced-collection.php --post={slug} --category={category}
   ```

3. **Regenerate documentation after collection:**
   ```bash
   php v2/scripts/blog/safe-regenerate-documentation.php --post={slug} --category={category} --backup
   ```

### Issue 4: Validation Script Fails

**Symptoms:**

- `validate-documentation-quality.php` reports errors
- Quality score is low

**Solutions:**

1. **Check specific validation errors:**

   ```bash
   php v2/scripts/blog/validate-documentation-quality.php --post={slug} --category={category}
   ```

2. **Fix common issues:**

   - Missing manual sections: Add `<!-- BEGIN MANUAL -->` markers
   - Unpopulated placeholders: Run auto-fill script
   - Missing data files: Re-run data collection

3. **Validate placeholder completion:**
   ```bash
   php v2/scripts/blog/validate-placeholder-completion.php --post={slug} --category={category}
   ```

### Issue 5: Progress Tracker Shows Wrong Status

**Symptoms:**

- Progress tracker shows posts as "in progress" when they're complete
- Status doesn't match actual file state

**Solutions:**

1. **Regenerate progress tracker:**

   ```bash
   php v2/scripts/blog/generate-review-progress-tracker.php
   ```

2. **Verify completion criteria:**

   - All placeholders filled
   - Manual sections contain actual content
   - All 4 documentation files present (3 for Inside Ordio)

3. **Check for discrepancies:**
   ```bash
   # Compare status files
   diff docs/content/blog/MANUAL_REVIEW_STATUS.md docs/content/blog/REVIEW_PROGRESS_TRACKER.md
   ```

### Issue 6: Script Errors or Timeouts

**Symptoms:**

- Scripts fail with errors
- Scripts timeout on large batches

**Solutions:**

1. **Check PHP configuration:**

   ```bash
   php -i | grep -E "(memory_limit|max_execution_time)"
   ```

2. **Increase limits if needed:**

   - Edit script: `ini_set('memory_limit', '512M');`
   - Edit script: `set_time_limit(600);`

3. **Process in smaller batches:**

   ```bash
   # Process by category
   php v2/scripts/blog/auto-fill-placeholders.php --category=lexikon
   php v2/scripts/blog/auto-fill-placeholders.php --category=ratgeber
   ```

4. **Check script logs:**
   ```bash
   tail -f logs/blog-scripts.log
   ```

### Issue 7: Related Resources Not Found

**Symptoms:**

- `related-resources.json` missing or empty
- Tool/template links not available

**Solutions:**

1. **Regenerate related resources:**

   ```bash
   php v2/scripts/blog/map-post-related-resources.php --post={slug} --category={category}
   ```

2. **Check resource data files:**

   ```bash
   # Verify tools/templates data exists
   ls v2/data/tools/*.json
   ls v2/data/templates/*.json
   ```

3. **Verify cluster mapping:**
   ```bash
   cat docs/data/blog-cluster-mapping.json | jq '.posts[] | select(.url | contains("'"{slug}"'"))'
   ```

### Issue 8: Post Not in Cluster Mapping / Related Posts Seem Wrong

**Symptoms:**

- New post doesn't appear in related posts carousels
- Pillar links or tools links missing for a post
- `validate-cluster-mapping.py` reports URL does not resolve

**Solutions:**

1. **Run audit to identify gaps:**
   ```bash
   python3 v2/scripts/blog/audit-cluster-mapping-coverage.py
   ```
   See `docs/content/blog/CLUSTER_MAPPING_COVERAGE_AUDIT.md` for missing posts.

2. **Add single post:**
   ```bash
   php v2/scripts/blog/add-post-to-cluster-mapping.php --post={slug} --category={lexikon|ratgeber|inside-ordio} --primary-cluster={cluster}
   ```
   Clusters: dienstplan, zeiterfassung, compliance, gastronomie, lohnabrechnung, personalverwaltung, tools, pflege, einzelhandel

3. **Batch add missing posts:**
   ```bash
   php v2/scripts/blog/add-missing-posts-to-cluster-mapping.php --dry-run   # Preview
   php v2/scripts/blog/add-missing-posts-to-cluster-mapping.php --write     # Apply
   ```

4. **Fix mapping URLs that don't resolve:** Use canonical URLs (e.g. `gastronomie-mindestlohn` not `2025-gastronomie-mindestlohn`). Run `validate-cluster-mapping.py` after changes.

5. **Related posts logic:** Cluster mapping is fallback when post JSON lacks `clusters`. See `RELATED_POSTS_LOGIC.md`.

## Validation Checklist

Before marking a post as complete:

- [ ] All automated placeholders filled (`{SEO_SCORE}`, `{REPORT_TIMESTAMP}`, etc.)
- [ ] Manual sections contain actual content (not template text)
- [ ] All 4 documentation files present (3 for Inside Ordio)
- [ ] Quality validation passes (`validate-documentation-quality.php`)
- [ ] Placeholder validation passes (`validate-placeholder-completion.php`)
- [ ] Manual notes added in MANUAL_NOTES.md (optional but recommended)

## Quick Reference Commands

### Regeneration

```bash
# Safe regeneration with backup
php v2/scripts/blog/safe-regenerate-documentation.php --post={slug} --category={category} --backup

# Regenerate all posts
php v2/scripts/blog/safe-regenerate-documentation.php --all --backup
```

### Auto-Fill Placeholders

```bash
# Single post
php v2/scripts/blog/auto-fill-placeholders.php --post={slug} --category={category}

# All posts
php v2/scripts/blog/auto-fill-placeholders.php --all

# Dry run (test first)
php v2/scripts/blog/auto-fill-placeholders.php --all --dry-run
```

### Validation

```bash
# Quality validation
php v2/scripts/blog/validate-documentation-quality.php --post={slug} --category={category}

# Placeholder completion
php v2/scripts/blog/validate-placeholder-completion.php --post={slug} --category={category}

# All posts
php v2/scripts/blog/validate-documentation-quality.php --all
```

### Data Collection

```bash
# Re-run SEO analysis
php v2/scripts/blog/analyze-post-seo.php --post={slug} --category={category}

# Re-run advanced collection
php v2/scripts/blog/run-all-advanced-collection.php --post={slug} --category={category}

# Regenerate related resources
php v2/scripts/blog/map-post-related-resources.php --post={slug} --category={category}
```

### Progress Tracking

```bash
# Regenerate progress tracker
php v2/scripts/blog/generate-review-progress-tracker.php

# Generate priority list
php v2/scripts/blog/generate-review-priority-list.php

# Generate placeholder report
php v2/scripts/blog/generate-template-placeholders-report.php
```

## Getting Help

If issues persist:

1. **Check logs:**

   ```bash
   tail -100 logs/blog-scripts.log
   ```

2. **Verify file permissions:**

   ```bash
   ls -la v2/scripts/blog/
   ```

3. **Test on single post first:**

   - Always test scripts on one post before batch processing
   - Verify results before proceeding

4. **Review documentation:**
   - `MANUAL_REVIEW_WORKFLOW.md` - Complete workflow guide
   - `DATA_INTEGRATION_GUIDE.md` - Data collection guide
   - `PLACEHOLDER_COMPLETION_STRATEGY.md` - Placeholder completion guide

## Prevention Best Practices

1. **Always use safe regeneration:**

   - Use `safe-regenerate-documentation.php` with `--backup` flag
   - Test on one post first

2. **Validate before proceeding:**

   - Run validation scripts after each major change
   - Check placeholder completion regularly

3. **Backup before changes:**

   - Create backups before batch operations
   - Keep backup copies of important files

4. **Process in batches:**

   - Don't process all posts at once
   - Process by category or priority level
   - Validate after each batch

5. **Document issues:**
   - Note any issues encountered
   - Update troubleshooting guide with solutions
   - Share learnings with team