# blog-manual-review Full Instructions

## Overview

Rules for conducting manual review of blog post documentation, ensuring data-driven recommendations are refined with human expertise while preserving manual edits during automated regeneration.

## Keyword-First Rule

**When improving a post:** Always run `derive-target-keywords.php` first if GSC data exists. Never run SISTRIX/FAQ collectors with stale or wrong `primary_keyword`. Wrong keywords cause all downstream data (SISTRIX, FAQ research, SERP features) to be irrelevant.

```bash
php v2/scripts/blog/derive-target-keywords.php --post={slug} --category={category} [--update-post]
```

## Full Rework Rule

**When Quality Score \< 60 OR Word Count \< 80% target OR no SERP_ANALYSIS.md:** Full rework is MANDATORY. Do not patch. Create from scratch; preserve calculators, videos, essential images only.

**Before editing content:** Run `php v2/scripts/blog/validate-improvement-readiness.php --post={slug} --category={category}`. If it fails, complete Phases 1–3 first (data collection, analysis, SERP research + outline).

**Before Phase 4:** Run `collect-post-competitor-analysis.php`. Review `data/competitor-analysis.json` (headings, topics, word counts of top 10). SERP review: Search primary + 2 secondary keywords. Document top 10 URLs, PAA questions, featured snippet per [SERP_REVIEW_CHECKLIST.md](docs/content/blog/posts/_templates/SERP_REVIEW_CHECKLIST.md).

**New posts:** Require `competitive-depth-analysis.md` and SERP_ANALYSIS.md completion (no placeholders) before outline. Run `validate-content-outline-quality.php` before content. See [blog-content-creation-gate.mdc](.cursor/rules/blog-content-creation-gate.mdc) for gate logic.

## Quick Start: Resume Runbook

**When user says "Review post X":** Use [MANUAL_REVIEW_RESUME_RUNBOOK.md](docs/content/blog/MANUAL_REVIEW_RESUME_RUNBOOK.md) as the single entry point. It provides step-by-step: backup → data validation → keyword derivation → documentation → review → content/FAQ updates → validation.

## When to Conduct Manual Review

### Initial Review

- After initial documentation generation
- When new data sources are integrated
- After major content updates

### FAQ Gap Remediation

- **Posts with 0 FAQs or \<10 FAQs:** Conduct manual review per [FAQ_GAP_REMEDIATION_RUNBOOK.md](docs/content/blog/FAQ_GAP_REMEDIATION_RUNBOOK.md)
- Run `python3 v2/scripts/blog/audit-faq-gap-analysis.py` to identify gaps
- **Check H2-FAQ overlap:** Run `php v2/scripts/blog/check-h2-faq-overlap.php --post={slug} --category={category}`; remove duplicates.
- One-by-one manual review required; no automated content creation

### Regular Review

- **Quarterly:** Review all posts for content freshness
- **Monthly:** Review high-priority posts (Score ≥ 60)
- **As Needed:** When performance metrics change significantly

### Before Implementation

- Always complete manual review before implementing improvements
- Ensures recommendations are actionable and aligned with business goals
- Validates data-driven insights with domain expertise

## Documentation Structure

### Dual-Section System

Each documentation file uses a dual-section structure:

**Automated Sections:**

- Marked with `<!-- BEGIN AUTOMATED -->` and `<!-- END AUTOMATED -->`
- Regenerated by scripts with latest data
- Contains data-driven recommendations
- Safe to regenerate (manual edits preserved)

**Manual Sections:**

- Marked with `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->`
- Preserved during regeneration
- Contains human insights and refinements
- Never overwritten by scripts

### Required Files

1. **POST_ANALYSIS.md** - Content analysis and quality assessment
2. **SEO_REPORT.md** - SEO performance and keyword analysis
3. **INTERNAL_LINKS.md** - Internal linking analysis and opportunities
4. **IMPROVEMENT_PLAN.md** - Actionable improvement recommendations (Ratgeber/Lexikon only)
5. **MANUAL_NOTES.md** - Comprehensive manual review notes (never overwritten)

## Manual Review Workflow

### Step 1: Preparation

1. **Check Progress:**

   ```bash
   cat docs/content/blog/REVIEW_PROGRESS_TRACKER.md
   ```

2. **Prioritize Posts:**

   ```bash
   cat docs/content/blog/REVIEW_PRIORITY_LIST.md
   ```

3. **Generate Checklist:**
   ```bash
   php v2/scripts/blog/generate-manual-review-checklist.php --post={slug} --category={category}
   ```

### Step 2: Review Documentation

Navigate to: `docs/content/blog/posts/{category}/{slug}/`

**Review Order:**

1. **MANUAL_REVIEW_CHECKLIST.md**

   - Personalized checklist based on post's issues
   - Check off items as you complete them
   - Data-driven priority scoring included

2. **POST_ANALYSIS.md**

   - Review automated content analysis
   - Verify search intent alignment
   - Check SERP features integration
   - Assess competition levels
   - Add manual insights in manual section

3. **SEO_REPORT.md**

   - Review keyword performance data
   - Verify search intent classification
   - Check SERP features presence
   - Assess competition levels
   - Refine meta tag recommendations
   - Add SEO opportunities in manual section

4. **INTERNAL_LINKS.md**

   - Review current link inventory
   - Check domain opportunity-based suggestions
   - Assess related posts carousel
   - Add strategic link recommendations in manual section

5. **IMPROVEMENT_PLAN.md** (Ratgeber/Lexikon only)

   - Review automated recommendations
   - Prioritize actions based on data
   - Refine effort estimates
   - Add business context in manual section

6. **MANUAL_NOTES.md**
   - Document comprehensive review notes
   - Track implementation progress
   - Record expert insights
   - Never overwritten by scripts

### Step 3: Complete Template Placeholders

**Common Placeholders:**

- `{PRIMARY_KEYWORD_1}` → Replace with actual primary keyword
- `{VOLUME_1}` → Replace with SISTRIX volume data
- `{INTENT_ALIGNMENT}` → Assess and document alignment
- `{SEO_HIGH_PRIORITY_1}` → Identify high-priority SEO actions
- `{CONTENT_GAP_1}` → Identify specific content gaps
- `{LINK_OPPORTUNITY_1}` → Suggest strategic internal links

**Search for Placeholders:**

```bash
grep -r "To be\|{.*}" docs/content/blog/posts/{category}/{slug}/*.md
```

### Step 4: Validate Quality

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

**Expected Output:**

- ✅ Manual sections present
- ✅ Automated sections populated
- ✅ No unpopulated placeholders in automated sections
- ✅ Data integration complete

## Data-Driven Review Guidelines

### Search Intent Analysis

**Informational Intent:**

- Focus on comprehensive guides
- Answer all user questions
- Use structured formats (lists, tables)
- Target featured snippets

**Navigational Intent:**

- Ensure clear branding
- Optimize internal navigation
- Strengthen internal linking
- Focus on brand mentions

**Transactional Intent:**

- Include clear CTAs
- Mention products/services naturally
- Optimize conversion paths
- Focus on conversion-focused content

### SERP Features Optimization

**Featured Snippets:**

- Add concise, direct answers (40-60 words) in first paragraph
- Use structured formats (lists, tables, numbered steps)
- Target question-based queries
- Optimize for "what is", "how to", "why" queries

**People Also Ask (PAA):**

- Integrate PAA questions as FAQs
- Provide direct answers
- Use FAQ schema markup
- Structure answers clearly

**Knowledge Panels:**

- Optimize structured data (Schema.org)
- Ensure consistent entity mentions
- Build authority signals
- Focus on E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness)

### Competition-Based Prioritization

**Low Competition Keywords:**

- Quick-win opportunities
- Prioritize content expansion
- Target with new content sections
- Focus on ranking improvements

**Medium Competition Keywords:**

- Build authority
- Create comprehensive content
- Focus on outranking competitors
- Invest in content depth

**High Competition Keywords:**

- Long-term strategy
- Consider niche down approach
- Target secondary keywords
- Focus on user experience

### Domain Opportunity Cross-Referencing

- Identify posts close to ranking (positions 11-20)
- Suggest content updates to push higher
- Recommend internal linking strategies
- Cross-reference with competitor analysis

## Best Practices

### Content Review

1. **Verify Accuracy:**

   - Check factual accuracy
   - Verify current year (use `date +%Y` - currently 2026)
   - Ensure pricing is up-to-date (€89/Standort/Monat)
   - Validate URLs and links

2. **Assess Quality:**

   - Evaluate writing style and tone
   - Check for grammatical errors
   - Ensure readability
   - Verify formatting consistency

3. **Identify Gaps:**
   - Look for missing information
   - Suggest new sections
   - Identify depth opportunities
   - Recommend multimedia integration

### SEO Review

1. **Keyword Strategy:**

   - Verify primary/secondary keywords
   - Suggest alternative keywords
   - Identify long-tail opportunities
   - Refine keyword placement

2. **Meta Data:**

   - Propose engaging meta titles
   - Optimize meta descriptions
   - Ensure keyword inclusion
   - Verify length requirements

3. **Schema Markup:**
   - Identify advanced schema opportunities
   - Suggest HowTo, Product, Review schemas
   - Verify existing schema quality
   - Ensure validation

### Internal Linking Review

1. **Link Quality:**

   - Verify relevance of links
   - Check anchor text optimization
   - Ensure contextual placement
   - Validate link targets

2. **Related Posts:**

   - Evaluate automated suggestions
   - Propose manual overrides if needed
   - Ensure topical relevance
   - Check for content cluster alignment

3. **Cross-Page Type Linking:**
   - Link to tools/calculators
   - Link to templates/downloads
   - Link to product pages
   - Link to comparison pages

## Safe Regeneration

### When to Regenerate

- After data collection updates
- When new data sources are integrated
- After fixing data collection issues
- Before starting manual review (to ensure latest data)

### How to Regenerate Safely

**Always use safe regeneration:**

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

**For multiple posts:**

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

**Dry Run (Test First):**

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

### What Gets Preserved

- All content in `<!-- BEGIN MANUAL -->` sections
- `docs/content/blog/posts/{category}/{slug}/MANUAL_NOTES.md` file (never overwritten, per-post file)
- Manual edits to automated sections (if outside markers)

### What Gets Regenerated

- Content in `<!-- BEGIN AUTOMATED -->` sections
- Data-driven recommendations
- API-integrated metrics
- Template placeholders (if data available)

## Quality Assurance

### Validation Checklist

After completing manual review:

- [ ] All manual sections populated with insights
- [ ] Template placeholders completed
- [ ] Data integration verified
- [ ] Quality validation passed
- [ ] Manual notes documented
- [ ] Implementation priorities set

### Validation Script

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

**Checks Performed:**

- Manual section markers present
- Automated section markers present
- No unpopulated placeholders in automated sections
- Data integration completeness
- File structure integrity

## Troubleshooting

### Manual Sections Missing After Regeneration

**Symptoms:** Manual sections disappeared after regeneration

**Solutions:**

1. Check if safe regeneration was used
2. Verify manual section markers are correct
3. Check `preserve-manual-edits.php` logs
4. Restore from backup if needed

### Placeholders Not Populated

**Symptoms:** Placeholders like `{VOLUME_1}` still present after regeneration

**Solutions:**

1. Verify data files exist: `ls docs/content/blog/posts/{category}/{slug}/data/`
2. Check data file format: `cat docs/content/blog/posts/{category}/{slug}/data/keywords-sistrix.json`
3. Re-run data collection if needed
4. Check script logs for errors

### Data Integration Incomplete

**Symptoms:** Search intent, SERP features, or competition data missing

**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 if needed:
   ```bash
   php v2/scripts/blog/run-all-advanced-collection.php
   ```
3. Regenerate documentation after collection

## Priority Scoring

### Data-Driven Priority Factors

1. **Search Intent Alignment:** High priority if misaligned
2. **SERP Features:** High priority if opportunities present
3. **Competition Levels:** High priority for low-competition keywords
4. **Domain Opportunities:** High priority if close to ranking
5. **Performance Metrics:** High priority if underperforming

### Manual Priority Override

- Use business goals to adjust priorities
- Consider resource availability
- Factor in content freshness needs
- Account for competitive landscape

## Blog Post Improvement Process

**For comprehensive blog post improvement:** See `.cursor/rules/blog-improvement-process.mdc` and `docs/content/blog/BLOG_POST_IMPROVEMENT_PROCESS.md` for the complete manual-focused improvement workflow.

**Improvement Process Integration:**

- Manual review is part of the improvement process
- Data collection informs improvement decisions
- SERP analysis guides content strategy
- Quality validation ensures standards met

## Related Documentation

- **Blog Post Improvement Process:** `docs/content/blog/BLOG_POST_IMPROVEMENT_PROCESS.md` - Complete improvement workflow
- **Manual Review Workflow:** `docs/content/blog/guides/MANUAL_REVIEW_WORKFLOW.md`
- **Data Integration Guide:** `docs/content/blog/guides/DATA_INTEGRATION_GUIDE.md`
- **Preservation System Guide:** See `preserve-manual-edits.php` inline documentation
- **Implementation Guide:** `docs/content/blog/IMPLEMENTATION_AUTOMATION_GUIDE.md`
- **Quality Validation:** `v2/scripts/blog/validate-documentation-quality.php`

## Scripts

### Review Preparation

- `generate-manual-review-checklist.php` - Generate personalized checklist
- `validate-documentation-quality.php` - Validate documentation quality
- `validate-placeholder-completion.php` - Validate placeholder completion (NEW)

### Placeholder Management

- `auto-fill-placeholders.php` - Auto-fill SEO_SCORE and REPORT_TIMESTAMP placeholders (NEW)
- `generate-template-placeholders-report.php` - Generate placeholder inventory report

### Safe Regeneration

- `safe-regenerate-documentation.php` - Safe regeneration with preservation
- `preserve-manual-edits.php` - Extract/restore manual sections

### Data Collection

- `run-all-data-collection.php` - Run all data collection
- `run-all-advanced-collection.php` - Run advanced data collection

### Progress Tracking

- `generate-review-progress-tracker.php` - Generate progress tracker
- `generate-review-priority-list.php` - Generate priority list
- `generate-priority-dashboard.php` - Generate priority dashboard

## Troubleshooting

See `docs/content/blog/TROUBLESHOOTING_GUIDE.md` for comprehensive troubleshooting guide covering:

- Manual sections missing after regeneration
- Placeholders not populated
- Data integration incomplete
- Validation script failures
- Progress tracker discrepancies
- Script errors and timeouts
- Related resources not found

## Quick Reference

See `docs/content/blog/QUICK_REFERENCE_GUIDE.md` for quick reference covering:

- Common commands
- Placeholder completion
- Completion checklist
- File locations
- Priority levels
- Workflow summary

## Quality Assurance

See `docs/content/blog/QUALITY_ASSURANCE_CHECKLIST.md` for comprehensive QA checklist covering:

- Pre-review checklist
- Manual review completion checklist
- Content quality checklist
- Validation checklist
- Post-review checklist

## Batch Review Process

See `docs/content/blog/guides/BATCH_REVIEW_GUIDE.md` for batch review guide covering:

- Batch size recommendations
- Batch selection strategy
- Batch review process
- Quality standards
- Efficiency tips
- Common patterns
- Validation checklist

## Additional Documentation

- `docs/content/blog/guides/PLACEHOLDER_COMPLETION_STRATEGY.md` - Strategic approach to completing placeholders
- `docs/content/blog/guides/GAP_REMEDIATION_STRATEGY.md` - Strategy for remediating content gaps
- `docs/content/blog/guides/LINKING_STRATEGY_GUIDE.md` - Comprehensive internal linking guide
- `docs/content/blog/guides/SEO_BEST_PRACTICES_2026.md` - Current SEO best practices
- `docs/content/blog/CONTENT_QUALITY_STANDARDS_2026.md` - Content quality standards

## Version History

- **2026-01-11:** Initial version with dual-section system, preservation workflow, and data-driven review guidelines
- **2026-01-11:** Added auto-fill placeholders script, validation scripts, troubleshooting guide, and quick reference guide
- **2026-01-11:** Added quality assurance checklist, batch review guide, and additional documentation references