# Improvement Plan Guide

**Last Updated:** 2026-01-15

Complete guide for understanding, editing, and regenerating improvement plans for blog posts.

## Overview

Improvement plans (`IMPROVEMENT_PLAN.md`) are automatically generated documentation files for Ratgeber and Lexikon blog posts. They provide actionable improvement recommendations based on content analysis, SEO metrics, link quality, and related resources.

## File Structure

### Auto-Generated Sections

The following sections are **automatically generated** from analysis data and will be overwritten during regeneration:

1. **Quick Summary (From Reports)**
   - Current Status (Quality Score, Priority Level, Word Count, SEO Score)
   - Top Improvement Priorities (3 items generated from data)

**Data Sources:**
- `related-resources.json` - Tool/template/download links
- `links-analysis.json` - Link quality scores
- `seo-analysis.json` - SEO metrics
- `content-analysis.json` - Word count, FAQ count

### Manual Sections (Preserved)

Content between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers is **preserved** during regeneration:

1. **Manual Improvement Notes**
2. **Manual Improvement Observations**
3. **Manual Improvement Priorities** (High/Medium/Low)

**Placeholders in Manual Sections:**
- `{MANUAL_IMPROVEMENT_NOTES}` - Add your notes here
- `{MANUAL_IMPROVEMENT_OBSERVATION_1}` - Add observations
- `{MANUAL_IMPROVEMENT_HIGH_PRIORITY_1}` - Add high-priority items

These placeholders remain as-is for manual editing and are **never auto-populated**.

## Regeneration Process

### When to Regenerate

Regenerate improvement plans when:
- Analysis data files are updated (`related-resources.json`, `seo-analysis.json`, etc.)
- Reports are regenerated (`data/reports/` folder)
- Content or SEO metrics change significantly

### How to Regenerate

**Preferred (preserves manual sections):**
```bash
php v2/scripts/blog/safe-regenerate-documentation.php --post={slug} --category={category} --backup
```

**Alternative (overwrites; use when manual preservation not needed):**
```bash
php v2/scripts/blog/generate-post-documentation.php --post={slug} --category={category}
```

**All Posts:**
```bash
php v2/scripts/blog/generate-post-documentation.php --all
```

**Note:** `generate-improvement-plan.php` outputs improvements.json only (legacy). For IMPROVEMENT_PLAN.md, use generate-post-documentation or safe-regenerate-documentation.

### What Gets Preserved

✅ **Preserved:**
- Content between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers
- Manually edited "Top Improvement Priorities" (if no placeholders present)

❌ **Overwritten:**
- Quick Summary section (if contains placeholders)
- Auto-generated improvement priorities
- SEO scores and metrics

## Editing Guidelines

### Safe to Edit

✅ **Always Safe:**
- Content between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers
- Manual improvement notes, observations, and priorities

✅ **Safe (but will be overwritten on regeneration):**
- Quick Summary section (if you want temporary notes)

### Not Recommended

❌ **Don't Edit:**
- Placeholders like `{QUICK_IMPROVEMENT_1}` - these are auto-generated
- Placeholders like `{MANUAL_IMPROVEMENT_NOTES}` - these are for manual input only

### Best Practices

1. **Add Manual Insights:**
   - Use the manual sections for expert observations
   - Add context that data-driven analysis can't provide
   - Document strategic decisions and priorities

2. **Review Auto-Generated Priorities:**
   - Check if the 3 auto-generated priorities are accurate
   - If not, add manual notes explaining why
   - Consider if data sources need updating

3. **Preserve Important Content:**
   - If you manually edit the Quick Summary, ensure it doesn't contain placeholders
   - Otherwise, it will be overwritten on regeneration

## Data Sources for Auto-Generation

### Quick Improvement Priorities

Generated from:

1. **Missing Tool Links** (`related-resources.json`)
   - Format: "Add X tool links - Critical for conversions and user experience"

2. **Missing Template Links** (`related-resources.json`)
   - Format: "Add X template links - Valuable resources for readers"

3. **Missing Download Links** (`related-resources.json`)
   - Format: "Add X download links - Additional value for readers"

4. **Link Quality Score** (`links-analysis.json`)
   - Format: "Improve link quality score from X/100 to 70+ target"
   - Only if score < 70

5. **SEO Score** (`seo-analysis.json`)
   - Format: "Improve SEO score from X/100 to 70+ target"
   - Only if score < 70

6. **Word Count** (`content-analysis.json`)
   - Format: "Expand content by X words to reach 1,200+ target"
   - Only if word count < 1200

7. **FAQ Count** (`content-analysis.json`)
   - Format: "Add X FAQs for AEO/GEO optimization"
   - Only if FAQ count < 5

**Priority Order:**
1. Tool links (highest priority)
2. Template links
3. Download links
4. Link quality score
5. SEO score
6. Word count
7. FAQ count

## Troubleshooting

### Placeholders Not Populated

**Issue:** `{QUICK_IMPROVEMENT_1}` remains as placeholder after regeneration.

**Solutions:**
1. Check if `related-resources.json` exists and has data
2. Verify `seo-analysis.json`, `links-analysis.json`, `content-analysis.json` exist
3. Run regeneration script and check for errors
4. Verify script has access to all data files

### Manual Content Lost

**Issue:** Manual edits outside `<!-- BEGIN MANUAL -->` markers were lost.

**Solutions:**
1. Check if content contained placeholders (will be overwritten)
2. Move important manual content to `<!-- BEGIN MANUAL -->` section
3. Use `MANUAL_NOTES.md` for content that should never be overwritten

### Preservation Not Working

**Issue:** Content between markers was overwritten.

**Solutions:**
1. Verify markers are correct: `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->`
2. Check for syntax errors in markdown file
3. Ensure markers are on separate lines
4. Run validation script: `php v2/scripts/blog/validate-documentation-quality.php`

## Related Documentation

- `docs/content/blog/posts/README.md` - Blog post documentation structure
- `docs/content/blog/guides/REVIEW_WORKFLOW.md` - Review workflow
- `docs/content/blog/POST_REVIEW_CHECKLIST.md` - Review checklist
- `v2/scripts/blog/generate-post-documentation.php` - Generation script

## Script Reference

### generate-post-documentation.php

**Purpose:** Generate all documentation files for blog posts, including improvement plans.

**Key Functions:**
- `generateQuickImprovements()` - Generate top 3 priorities from data
- `generateImprovementPlan()` - Generate complete improvement plan
- `extractManualSections()` - Preserve manual content
- `restoreManualSections()` - Restore preserved content

**Preservation Logic:**
1. Extract manual sections before regeneration
2. Generate new content from template and data
3. Restore manual sections after generation
4. Preserve manually edited Quick Summary (if no placeholders)

## Examples

### Example: Auto-Generated Priorities

```markdown
**Top Improvement Priorities:**

- Add 5 tool links - Critical for conversions and user experience
- Add 2 template links - Valuable resources for readers
- Improve link quality score from 44/100 to 70+ target
```

### Example: Manual Section

```markdown
<!-- BEGIN MANUAL -->

## Manual Improvement Plan & Insights (EDITABLE)

### Manual Improvement Notes

**Overall Assessment:**
This post has excellent content quality but low traffic. Critical improvements needed: tool/template links, SEO score improvement, and better internal linking quality.

**Quick Wins:**
1. Add 5 tool links - immediate conversion opportunity
2. Add 2 template links - valuable resources
3. Optimize existing links - improve quality score

<!-- END MANUAL -->
```

## Summary

- ✅ Auto-generated sections: Quick Summary, Top Improvement Priorities
- ✅ Manual sections: Content between `<!-- BEGIN MANUAL -->` markers
- ✅ Placeholders: `{QUICK_IMPROVEMENT_*}` auto-populated, `{MANUAL_IMPROVEMENT_*}` manual only
- ✅ Preservation: Manual sections always preserved, Quick Summary preserved if manually edited (no placeholders)
- ✅ Regeneration: Run `generate-post-documentation.php` to update auto-generated content