# Improvement Plan Prevention Guide

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

Prevention measures and best practices to avoid overwriting manual content in improvement plans.

## Problem Summary

**Issue:** Manual content in `IMPROVEMENT_PLAN.md` files was overwritten when scripts regenerated files from templates, replacing valuable manual insights with empty placeholders.

**Root Cause:**
- Script regenerated entire files from templates
- Placeholders (`{QUICK_IMPROVEMENT_1}`, etc.) weren't populated
- Manual content outside `<!-- BEGIN MANUAL -->` markers was lost
- Preservation logic only protected content between markers

## Prevention Measures Implemented

### 1. Auto-Population of Placeholders

**Fix:** Script now generates actual improvement priorities from analysis data instead of leaving placeholders empty.

**Implementation:**
- `generateQuickImprovements()` function extracts top 3 priorities from:
  - Related resources (tools, templates, downloads)
  - Link quality scores
  - SEO scores
  - Content metrics (word count, FAQ count)

**Result:** Placeholders are always populated with real data, never left empty.

### 2. Enhanced Preservation Logic

**Fix:** Preservation logic now detects and preserves manually edited Quick Summary sections.

**Implementation:**
- `extractManualSections()` checks for manual edits in Quick Summary
- Only preserves if content doesn't contain placeholders
- `restoreManualSections()` restores preserved Quick Summary content

**Result:** Manual edits to Quick Summary are preserved if they don't contain placeholders.

### 3. Clear Section Separation

**Fix:** Template clearly separates auto-generated and manual sections.

**Implementation:**
- Auto-generated: Quick Summary (populated from data)
- Manual: Content between `<!-- BEGIN MANUAL -->` markers (always preserved)
- Placeholders: `{QUICK_IMPROVEMENT_*}` auto-populated, `{MANUAL_IMPROVEMENT_*}` manual only

**Result:** Clear understanding of what gets overwritten vs preserved.

## Best Practices for Editors

### ✅ DO

1. **Edit Manual Sections Only**
   - Always edit content between `<!-- BEGIN MANUAL -->` markers
   - These sections are guaranteed to be preserved

2. **Use Placeholders Correctly**
   - `{MANUAL_IMPROVEMENT_NOTES}` - Replace with your notes
   - `{MANUAL_IMPROVEMENT_OBSERVATION_1}` - Replace with observations
   - These are for manual input only, never auto-populated

3. **Review Auto-Generated Content**
   - Check if auto-generated priorities are accurate
   - Add manual notes if you disagree with priorities
   - Update data sources if priorities are incorrect

4. **Test Regeneration**
   - Before regenerating all posts, test on 1-2 sample posts
   - Verify manual content is preserved
   - Check that placeholders are populated

### ❌ DON'T

1. **Don't Edit Auto-Generated Sections**
   - Quick Summary section will be overwritten
   - If you need to add notes, use manual sections instead

2. **Don't Remove Markers**
   - `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers are required
   - Removing them will cause content to be overwritten

3. **Don't Add Placeholders Manually**
   - Don't add `{QUICK_IMPROVEMENT_1}` manually - it will be auto-populated
   - Don't expect `{MANUAL_IMPROVEMENT_*}` to be auto-populated

4. **Don't Regenerate Without Backup**
   - Always create backup before regenerating
   - Use git to track changes
   - Test on sample posts first

## Pre-Regeneration Checklist

Before running `generate-post-documentation.php`:

- [ ] **Backup Created**
  - [ ] Git commit current state
  - [ ] Or create manual backup of files

- [ ] **Data Files Updated**
  - [ ] `related-resources.json` exists and is current
  - [ ] `seo-analysis.json` exists and is current
  - [ ] `links-analysis.json` exists and is current
  - [ ] `content-analysis.json` exists and is current

- [ ] **Manual Content Protected**
  - [ ] Important content is in `<!-- BEGIN MANUAL -->` sections
  - [ ] Quick Summary edits don't contain placeholders (if preserving)

- [ ] **Test Run**
  - [ ] Test on 1-2 sample posts first
  - [ ] Verify preservation works correctly
  - [ ] Check placeholders are populated

- [ ] **Validation**
  - [ ] Run validation script after regeneration
  - [ ] Check for missing manual sections
  - [ ] Verify placeholders are replaced

## Post-Regeneration Validation

After running `generate-post-documentation.php`:

- [ ] **Manual Sections Preserved**
  - [ ] Content between `<!-- BEGIN MANUAL -->` markers intact
  - [ ] Manual notes, observations, priorities preserved

- [ ] **Placeholders Populated**
  - [ ] `{QUICK_IMPROVEMENT_1}`, `{QUICK_IMPROVEMENT_2}`, `{QUICK_IMPROVEMENT_3}` replaced with actual content
  - [ ] `{SEO_SCORE}` replaced with actual score
  - [ ] No empty placeholders remain

- [ ] **Content Quality**
  - [ ] Auto-generated priorities are accurate
  - [ ] SEO scores match analysis data
  - [ ] Quick Summary reflects current state

- [ ] **No Errors**
  - [ ] Script completed without errors
  - [ ] All files generated successfully
  - [ ] No missing data files

## Validation Scripts

### Check for Placeholders

```bash
# Find files with unpopulated placeholders
find docs/content/blog/posts -name "IMPROVEMENT_PLAN.md" -exec grep -l "{QUICK_IMPROVEMENT_1}" {} \;
```

### Validate Preservation

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

### Check Manual Sections

```bash
# Verify manual sections exist
find docs/content/blog/posts -name "IMPROVEMENT_PLAN.md" -exec grep -l "<!-- BEGIN MANUAL -->" {} \;
```

## Recovery Procedures

### If Manual Content Was Lost

1. **Check Git History**
   ```bash
   git log --all --full-history -- docs/content/blog/posts/{category}/{slug}/IMPROVEMENT_PLAN.md
   ```

2. **Restore from Backup**
   ```bash
   git checkout HEAD -- docs/content/blog/posts/{category}/{slug}/IMPROVEMENT_PLAN.md
   ```

3. **Re-add Manual Content**
   - Copy content to `<!-- BEGIN MANUAL -->` section
   - Ensure markers are correct
   - Test regeneration to verify preservation

### If Placeholders Not Populated

1. **Check Data Files**
   - Verify all JSON files exist
   - Check file permissions
   - Validate JSON syntax

2. **Run Script with Debug**
   ```bash
   php v2/scripts/blog/generate-post-documentation.php --post={slug} --category={category} 2>&1 | tee debug.log
   ```

3. **Check Function Output**
   - Verify `generateQuickImprovements()` returns data
   - Check `generateImprovementPlan()` receives correct parameters
   - Validate template replacement works

## Monitoring

### Regular Checks

- **Weekly:** Check for unpopulated placeholders
- **Monthly:** Validate preservation logic on sample posts
- **Quarterly:** Review all improvement plans for quality

### Automated Monitoring

Consider adding:
- Pre-commit hook to check for placeholders
- CI/CD validation of preservation logic
- Automated alerts for overwritten manual content

## Related Documentation

- `docs/content/blog/IMPROVEMENT_PLAN_GUIDE.md` - Complete usage guide
- `docs/content/blog/posts/_templates/IMPROVEMENT_PLAN.md` - Template file
- `v2/scripts/blog/generate-post-documentation.php` - Generation script
- `.cursor/rules/blog-improvement-plans.mdc` - Cursor rules (if exists)

## Summary

**Key Prevention Measures:**
1. ✅ Auto-populate placeholders from data
2. ✅ Preserve manual sections automatically
3. ✅ Detect and preserve manually edited Quick Summary
4. ✅ Clear separation of auto vs manual sections
5. ✅ Validation scripts and checklists

**Editor Responsibilities:**
1. ✅ Edit only manual sections
2. ✅ Use placeholders correctly
3. ✅ Test before regenerating
4. ✅ Validate after regeneration

**Recovery:**
1. ✅ Git history for restoration
2. ✅ Backup before regeneration
3. ✅ Validation scripts for detection