# Script Issues & Fixes: Gefährdungsbeurteilung

**Last Updated:** 2026-03-16

## Issues Encountered

### 1. Primary Keyword Too Long
**Issue:** Initial `primary_keyword` was `"Gefährdungsbeurteilung: Definition, Durchführung & Dokumentation"` which was too long for SISTRIX API calls.

**Error:** 
- `collect-post-paa-questions.php` returned `no result`
- `collect-post-competitor-analysis.php` found 0 unique competitor URLs

**Fix:** Changed `primary_keyword` to `"Gefährdungsbeurteilung"` in `gefaehrdungsbeurteilung.json`

**Result:** ✅ PAA collection and competitor analysis worked after fix

### 2. H2 Format in CONTENT_OUTLINE.md
**Issue:** H2s were formatted as `## Title` but scripts expected `N. **H2: Title**` format.

**Error:**
- `generate-section-briefs.php` reported: `Error: No H2 sections found in CONTENT_OUTLINE.md`
- `check-outline-h2-overlap.php` reported: `Outline has fewer than 2 H2s`

**Fix:** Updated all 10 H2s in `CONTENT_OUTLINE.md` to format `N. **H2: Title**`

**Result:** ✅ Scripts recognized H2s correctly

### 3. update-post-content.php Parameter
**Issue:** Initial command missing `--html=` parameter.

**Error:** `Error: Must specify --html=path or --stdin`

**Fix:** Added `--html=docs/content/blog/posts/lexikon/gefaehrdungsbeurteilung/content-draft.html`

**Result:** ✅ Content updated successfully

### 4. add-faqs-to-post.php Parameter
**Issue:** Used `--source=` instead of `--faqs=` parameter.

**Error:** `Existing FAQs: 0`, `New FAQs added: 0`

**Fix:** Changed to `--faqs=docs/content/blog/posts/lexikon/gefaehrdungsbeurteilung/data/faq-answers-manual.json`

**Result:** ✅ 11 FAQs added successfully

### 5. Legal Citation Fetch Timeout
**Issue:** `mcp_web_fetch` for ArbSchG § 5 URL timed out.

**Error:** `Error: Fetch timed out while retrieving content`

**Fix:** Manually documented citation with URL in `LEGAL_CITATIONS.md`

**Result:** ✅ Legal citation documented

### 6. BetrSichV URL 404
**Issue:** BetrSichV URL returned 404.

**Error:** `Error fetching URL, status code: 404 Not Found`

**Fix:** Mentioned BetrSichV as relevant legal framework but didn't include direct link due to 404

**Result:** ✅ Legal framework mentioned appropriately

## Scripts Used Successfully

- ✅ `create-new-blog-post.php` - Post scaffold created
- ✅ `run-new-post-pipeline.php` - Data collection (after primary_keyword fix)
- ✅ `collect-post-paa-questions.php` - PAA questions collected
- ✅ `collect-post-competitor-analysis.php` - Competitor analysis completed
- ✅ `generate-section-briefs.php` - Section briefs generated (after H2 format fix)
- ✅ `update-post-content.php` - Content applied successfully
- ✅ `add-faqs-to-post.php` - FAQs added (after parameter fix)
- ✅ `validate-faq-schema.php` - FAQ schema validated
- ✅ `generate-blog-featured-image.py` - Featured image generated
- ✅ `sync-meta-to-posts.php` - Meta synced
- ✅ `generate-lead-capture-copy.php` - Lead capture copy generated
- ✅ `compare-content-to-competitors.php` - Validation passed
- ✅ `validate-section-depth.php` - Validation passed
- ✅ `validate-content-completeness.php` - Validation passed
- ✅ `validate-faq-quality.php` - Validation passed (100/100)
- ✅ `validate-new-post.php` - Validation passed (warnings only)
- ✅ `update-lexikon-tracking.py` - Tracking updated

## Recommendations

1. **Primary Keyword Validation:** Add validation to ensure `primary_keyword` is concise (max 2-3 words) before running SISTRIX scripts
2. **H2 Format Standardization:** Document expected H2 format in CONTENT_OUTLINE.md template
3. **Script Parameter Documentation:** Improve error messages to suggest correct parameter names
4. **Legal Citation Handling:** Consider caching legal citation URLs or using alternative sources