# Script Issues & Solutions: Sollarbeitszeit

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

## Overview

This document catalogs script issues encountered during post creation and their solutions.

## Issue 1: PAA Question Collection Failure

**Script:** `collect-post-paa-questions.php`  
**Error:** SISTRIX API returned no results  
**Root Cause:** Primary keyword was too specific: "Sollarbeitszeit: Definition, Planung & Berechnung"

**Solution:**
- Shortened primary keyword to "Sollarbeitszeit" in post JSON
- Updated `meta.keywords` to match
- Re-ran collection script successfully
- Created manual PAA questions file (`paa-questions-manual.json`) with 15 curated questions

**Prevention:**
- Use shorter, more generic primary keywords for automated collection
- Always verify keyword length before running pipeline
- Have manual PAA questions ready as backup

## Issue 2: FAQ Generation Filtering Too Aggressively

**Script:** `generate-faq-questions.php`  
**Issue:** Script only generated 6 FAQs (target: 10-15)  
**Warnings:** "Skipping off-topic question", "Skipping duplicate question"

**Root Cause:**
- Script's topic relevance filtering was too strict
- Manual PAA questions were marked as "off-topic" despite being highly relevant
- Similar to issue encountered with "Ruhezeiten" post

**Solution:**
- Created manual FAQ answers file (`faq-answers-manual.json`) with 14 FAQs
- Used `add-faqs-to-post.php` to apply manual FAQs
- All 14 FAQs validated successfully (1 skipped as H2-overlapping)

**Prevention:**
- Review script filtering logic for overly aggressive topic relevance checks
- Consider manual FAQ creation for niche topics
- Document manual FAQ patterns for future posts

## Issue 3: Lead Capture Copy Generation Missing Benefit Mapping

**Script:** `generate-lead-capture-copy.php`  
**Error:** "No benefit mapping for slug 'sollarbeitszeit'"

**Root Cause:**
- Script's `_slugToBenefit()` function lacked mapping for "sollarbeitszeit"

**Solution:**
- Added benefit mapping: `'sollarbeitszeit' => 'Sollarbeitszeit im Dienstplan plant und automatisch mit Ist-Arbeitszeit vergleicht'`
- Created manual lead capture copy entry in `lead_capture_copy.php`
- Updated script for future use

**Prevention:**
- Add benefit mappings proactively when creating new posts
- Review script's benefit mapping list before running
- Document benefit mapping patterns

## Issue 4: Competitor Analysis Found No Results

**Script:** `collect-post-competitor-analysis.php`  
**Issue:** Found 0 unique competitor URLs  
**Root Cause:** Low competition keyword (200 searches/month), niche term

**Solution:**
- Accepted as expected for low-volume keyword
- Focused content strategy on differentiation from "Sollstunden"
- Created comprehensive content based on manual research

**Prevention:**
- For low-volume keywords, expect minimal competitor data
- Use manual research and differentiation strategy
- Focus on comprehensive coverage rather than competitive analysis

## Script Performance Summary

### Scripts Used Successfully

- ✅ `create-new-blog-post.php` - Scaffold creation
- ✅ `run-new-post-pipeline.php` - Initial data collection (after keyword fix)
- ✅ `generate-section-briefs.php` - Section briefs generation
- ✅ `update-post-content.php` - Content application
- ✅ `add-faqs-to-post.php` - FAQ application
- ✅ `validate-faq-schema.php` - FAQ validation
- ✅ `generate-blog-featured-image.py` - Image generation
- ✅ `sync-meta-to-posts.php` - Meta synchronization
- ✅ `add-new-post-to-related-carousels.php` - Related posts update
- ✅ `validate-new-post.php` - Post validation

### Scripts Requiring Manual Intervention

- ⚠️ `collect-post-paa-questions.php` - Required keyword fix
- ⚠️ `generate-faq-questions.php` - Required manual FAQ creation
- ⚠️ `generate-lead-capture-copy.php` - Required benefit mapping addition

## Recommendations

### For Future Posts

1. **Keyword Selection:** Use shorter, more generic primary keywords for automated collection
2. **FAQ Strategy:** For niche topics, prepare manual FAQs proactively
3. **Benefit Mapping:** Review and add benefit mappings before running lead capture copy script
4. **Low-Volume Keywords:** Expect minimal competitor data, focus on comprehensive coverage

### Script Improvements

1. **PAA Collection:** Improve handling of specific keywords (suggest shortening)
2. **FAQ Generation:** Review topic relevance filtering logic
3. **Benefit Mapping:** Add more comprehensive benefit mapping coverage
4. **Error Messages:** Provide clearer guidance when mappings are missing

---

**Note:** All script issues were resolved. Post creation completed successfully with manual interventions where needed.