# Script Issues & Solutions: Arbeitszeit

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

## Overview

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

## Issue 1: FAQ Answer Generation Missing OpenAI API Key

**Script:** `generate-faq-answers-ai.php` (called by `generate-faqs-complete.php`)  
**Error:** "OpenAI API key not configured. Set OPENAI_API_KEY environment variable, define OPENAI_API_KEY constant, or create v2/config/openai-api-key.php with api_key setting."  
**Root Cause:** OpenAI API key not configured in environment or config file

**Solution:**
- Created manual FAQ answers file (`faq-answers-optimized.json`) with 15 questions and answers
- Answers manually written based on generated PAA questions and post content
- All answers adhere to length (40-80 words), tone (du), and keyword requirements
- Used `add-faqs-to-post.php` to apply manual FAQs successfully

**Prevention:**
- Configure OpenAI API key before running FAQ generation scripts
- Have manual FAQ creation as backup option
- Document manual FAQ patterns for future posts

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

**Script:** `generate-lead-capture-copy.php`  
**Error:** "No benefit mapping for slug 'arbeitszeit'"  
**Root Cause:** Script's `_slugToBenefit()` function lacked mapping for "arbeitszeit"

**Solution:**
- Added benefit mapping to script: `'arbeitszeit' => 'Arbeitszeiten gesetzeskonform erfasst und dokumentiert'`
- Re-ran script successfully with `--write` flag
- Lead capture copy added to `v2/data/lead_capture_copy.php`

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

## Issue 3: Content Outline H2 Format Validation Failure

**Script:** `validate-content-outline-quality.php`  
**Error:** "No H2 sections found in CONTENT_OUTLINE.md"  
**Root Cause:** H2 sections used `### H2: Section Title` format instead of `**H2: Section Title**`

**Solution:**
- Updated all H2 sections in `CONTENT_OUTLINE.md` to use `**H2: Section Title**` format
- Re-ran validation scripts successfully
- All 10 H2 sections validated correctly

**Prevention:**
- Use correct H2 markdown format (`**H2: Section Title**`) from the start
- Check example `CONTENT_OUTLINE.md` files before creating new ones
- Document H2 format requirements

## Issue 4: SERP_ANALYSIS.md Placeholder Validation Failure

**Script:** `validate-improvement-readiness.php` and `validate-content-outline-quality.php`  
**Error:** "SERP_ANALYSIS.md has unchecked placeholders. Complete manual sections (Featured Snippet, PAA, Ranking Factors, Recommendations)"  
**Root Cause:** Placeholder checkboxes (`[ ]`) not marked as complete (`[x]`)

**Solution:**
- Updated `SERP_ANALYSIS.md` by replacing placeholder checkboxes with completed marks
- Filled in Featured Snippet, PAA, Ranking Factors, and Recommendations sections
- Marked relevant PAA questions as covered by H2s or FAQs
- Documented intentionally excluded off-topic PAA questions

**Prevention:**
- Complete SERP_ANALYSIS.md placeholders before running validation scripts
- Mark PAA questions as covered or intentionally excluded
- Document off-topic questions with rationale

## Script Performance Summary

### Scripts Used Successfully

- ✅ `create-new-blog-post.php` - Scaffold creation
- ✅ `run-new-post-pipeline.php` - Initial data collection
- ✅ `generate-section-briefs.php` - Section briefs generation
- ✅ `update-post-content.php` - Content application
- ✅ `add-faqs-to-post.php` - FAQ application (manual FAQs)
- ✅ `validate-faq-schema.php` - FAQ validation
- ✅ `generate-blog-featured-image.py` - Image generation
- ✅ `sync-meta-to-posts.php` - Meta synchronization
- ✅ `suggest-related-posts.php` - Related posts suggestion
- ✅ `add-new-post-to-related-carousels.php` - Related carousels update
- ✅ `generate-lead-capture-copy.php` - Lead capture copy (after benefit mapping addition)
- ✅ `validate-new-post.php` - Post validation
- ✅ `compare-content-to-competitors.php` - Content comparison
- ✅ `validate-section-depth.php` - Section depth validation

### Scripts Requiring Manual Intervention

- ⚠️ `generate-faq-answers-ai.php` - Required manual FAQ creation (API key missing)
- ⚠️ `generate-lead-capture-copy.php` - Required benefit mapping addition

## Recommendations

### For Future Posts

1. **FAQ Strategy:** Configure OpenAI API key or prepare manual FAQs proactively
2. **Benefit Mapping:** Review and add benefit mappings before running lead capture copy script
3. **Content Outline:** Use correct H2 markdown format (`**H2: Section Title**`) from the start
4. **SERP Analysis:** Complete all placeholders before running validation scripts

### Script Improvements

1. **FAQ Generation:** Improve error handling when API key is missing (suggest manual creation)
2. **Benefit Mapping:** Add more comprehensive benefit mapping coverage
3. **Error Messages:** Provide clearer guidance when mappings are missing
4. **Content Outline:** Validate H2 format before running validation scripts

---

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