# Manual Review Workflow

**Last Updated:** 2026-01-05

## Documentation Structure

### Automated Reports vs Master Documentation

The documentation system uses a **dual-structure approach**:

1. **Automated Reports** (`data/reports/` folder)

   - Generated automatically by scripts
   - Can be regenerated without affecting manual edits
   - Contains detailed automated analysis
   - Files: `content-analysis-report.md`, `seo-performance-report.md`, `keyword-opportunities-report.md`, `traffic-analysis-report.md`, `prioritization-score-report.md`

2. **Master Documentation** (root of post folder)
   - Contains quick summary from reports
   - Includes fully editable manual sections (between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->`)
   - Files: `POST_ANALYSIS.md`, `SEO_REPORT.md`, `INTERNAL_LINKS.md`, `IMPROVEMENT_PLAN.md`, `MANUAL_NOTES.md`

**Key Principle:** Automated reports provide rich data, master docs provide editable insights. Manual edits in master docs are preserved during regeneration.

## Prioritization System

Posts are prioritized using a comprehensive data-driven scoring system. See `PRIORITIZATION_SYSTEM_GUIDE.md` for details.

**Quick Start:**

1. Check `REVIEW_PRIORITY_LIST.md` for prioritized posts
2. Review `PRIORITY_DASHBOARD.md` for multiple priority views
3. Focus on high priority posts (score ≥ 70) first Guide

**Last Updated:** 2026-01-11

## Overview

This guide provides a systematic workflow for completing manual review of all blog posts. The system now includes:

- **Dual-Section Documentation:** Automated sections (regenerated safely) and manual sections (preserved during regeneration)
- **Data-Driven Recommendations:** Leveraging SISTRIX data (search intent, SERP features, competition levels, domain opportunities)
- **Safe Regeneration:** Manual edits are preserved when regenerating documentation
- **Quality Assurance:** Validation scripts ensure data integration completeness

The automated foundation is complete; now human review is needed to complete template placeholders and add expert insights.

## Quick Start

1. **Check Progress:** Review `REVIEW_PROGRESS_TRACKER.md` to see current status
2. **Prioritize:** Use `REVIEW_PRIORITY_LIST.md` to identify high-priority posts
3. **Review:** Follow the checklist in each post's `MANUAL_REVIEW_CHECKLIST.md`
4. **Update:** Complete template placeholders in documentation files
5. **Track:** Progress is automatically tracked in `REVIEW_PROGRESS_TRACKER.md`

## Step-by-Step Workflow

### Step 1: Preparation

1. Open `REVIEW_PRIORITY_LIST.md` to see prioritized posts
2. Open `REVIEW_PROGRESS_TRACKER.md` to see current progress
3. Open `TEMPLATE_PLACEHOLDERS_REPORT.md` to see what needs completion

### Step 2: Select a Post

**Recommended Order:**

1. High Priority posts (Score ≥ 60) - 41 posts
2. Medium Priority posts (Score 40-59) - 43 posts
3. Low Priority posts (Score < 40) - 15 posts

**Or by Category:**

- Start with Ratgeber (higher conversion potential)
- Then Lexikon (SEO-focused)
- Finally Inside Ordio (documentation only)

### Step 3: Review Post Documentation

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

**Files to Review:**

1. **MANUAL_REVIEW_CHECKLIST.md**

   - Contains personalized checklist based on post's issues
   - Check off items as you complete them

2. **POST_ANALYSIS.md**

   - Review content analysis
   - **Automated Section:** Contains data-driven recommendations (search intent, SERP features, competition analysis, domain opportunities)
   - **Manual Section:** Add your expert insights and refinements (preserved during regeneration)
   - Complete template placeholders marked with `{PLACEHOLDER}` or "To be..."
   - Verify word count, structure, FAQs

3. **SEO_REPORT.md**

   - Review SEO analysis
   - **Automated Section:** Contains competition-based keyword prioritization, SERP feature optimization recommendations, search intent alignment
   - **Manual Section:** Refine recommendations based on your expertise (preserved during regeneration)
   - Complete keyword recommendations
   - Refine meta tag suggestions
   - Add SEO opportunities

4. **INTERNAL_LINKS.md**

   - Review link analysis
   - **Automated Section:** Contains domain opportunity-based link suggestions
   - **Manual Section:** Add your link strategy insights (preserved during regeneration)
   - Identify missing link opportunities
   - Review related posts carousel
   - Add cross-page type linking strategy

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

   - Review improvement recommendations
   - **Automated Section:** Contains data-driven content expansion recommendations (search intent, SERP features, competition-based depth)
   - **Manual Section:** Refine priorities and effort estimates (preserved during regeneration)
   - Prioritize actions (High/Medium/Low)
   - Add effort estimates
   - Refine recommendations based on business goals

6. **MANUAL_NOTES.md** (NEW - Never overwritten)
   - Comprehensive manual review notes
   - Expert observations and insights
   - Implementation tracking
   - Review history
   - **Important:** This file is NEVER overwritten by scripts

### Step 4: Complete Template Placeholders

**Common Placeholders to Complete:**

- `{POST_TITLE}` → Replace with actual post title
- `{POST_SLUG}` → Replace with post slug
- `{CATEGORY}` → Replace with category name
- `{WORD_COUNT}` → Replace with actual word count
- `{SEO_SCORE}` → Replace with SEO score
- `{LINK_SCORE}` → Replace with link quality score
- `To be identified` → Add specific recommendations
- `To be calculated` → Add calculated values
- `To be listed` → Add actual lists
- `To be assessed` → Add assessment

**Search Pattern:**
Use your editor's search to find: `\{[A-Z_]+\}|To be (identified|calculated|listed|assessed|counted)`

### Step 5: Add Manual Insights

**Important:** All manual insights should be added in the **Manual Section** (between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers) or in `MANUAL_NOTES.md`. These sections are preserved during regeneration.

**For POST_ANALYSIS.md:**

- Content gaps you've identified
- Areas needing expansion
- Missing subtopics
- Quality improvements
- Refinements to data-driven recommendations

**For SEO_REPORT.md:**

- Keyword opportunities
- Meta tag refinements
- Schema markup opportunities
- AEO/GEO considerations
- Refinements to SERP feature optimization recommendations
- Search intent alignment adjustments

**For INTERNAL_LINKS.md:**

- Missing tool/template links
- Pillar page linking opportunities
- Related posts carousel improvements
- Cross-cluster linking strategy
- Domain opportunity link refinements

**For IMPROVEMENT_PLAN.md:**

- Priority adjustments
- Effort estimates
- Business impact assessments
- Implementation timeline
- Refinements to data-driven expansion recommendations

**For MANUAL_NOTES.md:**

- Comprehensive review notes
- Expert observations
- Implementation tracking
- Review history

### Step 6: Mark as Complete

1. Ensure all placeholders are completed
2. Verify all checklist items are checked
3. Add final notes if needed
4. Save all files

### Step 7: Update Progress

Run the progress tracker to update status:

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

## Review Checklist Template

For each post, verify:

### Content Quality

- [ ] Word count meets target (1,200+ words)
- [ ] Content depth is adequate
- [ ] FAQs are present and relevant (5+ FAQs)
- [ ] Content is accurate and up-to-date
- [ ] Structure is logical and easy to follow

### SEO Elements

- [ ] Meta title is optimized (30-60 chars, includes keyword)
- [ ] Meta description is optimized (70-160 chars, includes CTA)
- [ ] H1 tag includes primary keyword
- [ ] Keywords are naturally integrated
- [ ] Schema markup is present and correct

### Internal Linking

- [ ] Sufficient internal links (10+ recommended)
- [ ] Links to relevant tools/calculators
- [ ] Links to relevant templates/downloads
- [ ] Links to pillar pages (Ratgeber/Lexikon)
- [ ] Related posts carousel is relevant

### Improvement Plan (Ratgeber/Lexikon only)

- [ ] Priorities are assigned (High/Medium/Low)
- [ ] Effort estimates are realistic
- [ ] Recommendations are actionable
- [ ] Business impact is considered

## Batch Review Tips

### Efficient Workflow

1. **Group Similar Posts:** Review posts from same cluster together
2. **Use Templates:** Create templates for common improvements
3. **Focus Areas:** Prioritize high-impact improvements first
4. **Regular Breaks:** Review in batches of 5-10 posts

### Quality Control

1. **Consistency:** Ensure consistent formatting across posts
2. **Accuracy:** Verify all data and recommendations
3. **Completeness:** Ensure all placeholders are filled
4. **Relevance:** Verify recommendations are relevant to post

## Tools Available

### Review Scripts

- `generate-manual-review-checklist.php` - Generate personalized checklists with data-driven priority scoring
- `generate-review-progress-tracker.php` - Track review progress
- `validate-post-documentation.php` - Validate completeness
- `validate-documentation-quality.php` - Validate manual section preservation and data integration completeness

### Analysis Scripts

- `analyze-post-content.php` - Re-analyze content if needed
- `analyze-post-seo.php` - Re-analyze SEO if needed
- `analyze-post-links.php` - Re-analyze links if needed

### Safe Regeneration

- `safe-regenerate-documentation.php` - **RECOMMENDED:** Safely regenerate docs with manual edit preservation, validation, and rollback
- `preserve-manual-edits.php` - Extract and restore manual sections
- `generate-post-documentation.php` - Regenerate docs (now preserves manual sections automatically)
- `generate-improvement-plan.php` - Regenerate improvement plans

**Important:** Always use `safe-regenerate-documentation.php` with `--backup` flag for safe regeneration:

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

## Common Issues & Solutions

### Issue: Too Many Placeholders

**Solution:** Focus on high-priority placeholders first. Use find/replace for common patterns.

### Issue: Unclear Recommendations

**Solution:** Review the post content directly. Use your expertise to refine recommendations.

### Issue: Missing Data

**Solution:** Run analysis scripts again if data seems incorrect. Check data files in `data/` folder. Use `validate-documentation-quality.php` to check data integration completeness.

### Issue: Manual Edits Lost During Regeneration

**Solution:** This should not happen with the new system. If it does:

1. Use `safe-regenerate-documentation.php` with `--backup` flag
2. Check that manual sections are between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers
3. Use `preserve-manual-edits.php` to extract manual sections before regeneration
4. Check backups in `v2/data/blog/regeneration-backups/`

### Issue: Overwhelming Amount of Work

**Solution:** Focus on high-priority posts first. Use progress tracker to see incremental progress.

## Progress Tracking

### Check Current Status

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

### View Priority List

Open `REVIEW_PRIORITY_LIST.md` to see prioritized posts.

### View Placeholders Report

Open `TEMPLATE_PLACEHOLDERS_REPORT.md` to see what needs completion.

## Completion Criteria

A post is considered "reviewed" when:

1. ✅ All template placeholders are completed (in automated sections)
2. ✅ All checklist items are checked
3. ✅ Manual insights are added (in manual sections or MANUAL_NOTES.md)
4. ✅ Documentation is accurate and complete
5. ✅ Improvement plan is prioritized (Ratgeber/Lexikon only)
6. ✅ Data-driven recommendations are reviewed and refined
7. ✅ Quality validation passes (`validate-documentation-quality.php`)

## Next Steps After Review

1. **Implementation:** Use improvement plans to guide content updates
2. **Monitoring:** Track performance improvements
3. **Iteration:** Update documentation as content changes
4. **Validation:** Run final validation script

## Support Resources

- **Review Checklist:** `POST_REVIEW_CHECKLIST.md`
- **Review Workflow:** `REVIEW_WORKFLOW.md`
- **Priority List:** `REVIEW_PRIORITY_LIST.md`
- **Progress Tracker:** `REVIEW_PROGRESS_TRACKER.md`
- **Placeholders Report:** `TEMPLATE_PLACEHOLDERS_REPORT.md`
- **Content Gaps:** `CONTENT_GAPS_SUMMARY.md`
- **Internal Links:** `INTERNAL_LINKS_REVIEW_REPORT.md`
- **Data Integration Guide:** `DATA_INTEGRATION_GUIDE.md` (NEW)
- **Preservation System Guide:** See `preserve-manual-edits.php` documentation

## Notes

- Manual review is iterative - you can update documentation as you learn more
- Focus on quality over speed - thorough review is more valuable than quick completion
- Use your expertise - automated analysis supports but doesn't replace human judgment
- Regular progress checks help maintain momentum