# FAQ Gap Remediation Runbook

**Last Updated:** 2026-02-11

Step-by-step runbook for remediating blog posts with no FAQs or insufficient FAQs (< 10). Designed for manual, one-by-one review—nothing automated for content creation.

## Scope

- **Target:** Lexikon + Ratgeber posts (inside-ordio excluded)
- **Gap definition:** 0 FAQs or 1–9 FAQs (below minimum 10)
- **Best practice:** 10–15 FAQs per post, 40–80 words per answer

## Quick Reference

| Step | Action | Script/Path |
|------|--------|-------------|
| 1 | Identify gaps | `python3 v2/scripts/blog/audit-faq-gap-analysis.py` |
| 2 | Derive keywords | `derive-target-keywords.php` |
| 3 | Check data freshness | `check-data-freshness.php` |
| 4 | Collect FAQ research | `collect-faq-research-data.php` |
| 5 | Generate questions | `generate-faq-questions.php` |
| 6 | Generate answers | `generate-faq-answers-optimized.php` |
| 7 | Add FAQs to post | `add-faqs-to-post.php` |
| 8 | Validate | `validate-faq-quality.php`, `validate-faq-schema.php` |

## Pre-Work: Data Collection (If Missing)

If `docs/content/blog/posts/{category}/{slug}/data/` is missing or incomplete:

```bash
# GSC data (required for keyword derivation)
php v2/scripts/blog/collect-post-performance-gsc.php --post={slug} --category={category}

# SISTRIX keywords and SERP features
php v2/scripts/blog/collect-post-keywords-sistrix.php --post={slug} --category={category}
php v2/scripts/blog/collect-post-serp-features.php --post={slug} --category={category}

# FAQ research (combines PAA, GSC, keywords)
php v2/scripts/blog/collect-faq-research-data.php --post={slug} --category={category}
```

**Outputs:**
- `data/performance-gsc.json` – top queries, clicks, impressions
- `data/keywords-sistrix.json` – volume, competition
- `data/serp-features.json` – people_also_ask, related_searches
- `data/faq-research.json` – combined research data

## Per-Post Workflow

### Step 1: Keyword Derivation (CRITICAL)

**Rule:** Always run `derive-target-keywords.php` first if GSC data exists. Wrong keywords cause downstream data to be irrelevant.

```bash
php v2/scripts/blog/derive-target-keywords.php --post={slug} --category={category} --update-post
```

### Step 2: Data Freshness Check

```bash
php v2/scripts/blog/check-data-freshness.php --post={slug} --category={category} --max-age=7
```

If stale, re-run collection scripts from Pre-Work.

### Step 3: Manual Research Phase

1. **SISTRIX:** Review `data/serp-features.json` for `people_also_ask`, `related_searches`
2. **GSC:** Review `data/performance-gsc.json` → `metrics.top_queries` (sort by clicks, then impressions)
3. **Keywords:** Review `data/keywords-sistrix.json` for high-volume terms (≥50)
4. **Content:** Read post title, excerpt, H2s, first 500 words to understand topic

### Step 4: Question Generation (Assisted, Then Manual Curation)

```bash
php v2/scripts/blog/generate-faq-questions.php --post={slug} --category={category}
```

**Output:** `data/faq-questions.json` – use as starting point, **not** final.

**Manual curation:**
- Remove off-topic or low-relevance questions
- Remove nonsensical patterns ("Was kostet Freizeitausgleich?")
- Deduplicate semantic equivalents
- Order: definitions → how-to → requirements → when/why → edge cases
- Target 10–15 unique, high-value questions

### Step 5: Answer Generation (Assisted, Then Manual Review)

```bash
# Template mode (no API key required)
php v2/scripts/blog/generate-faq-answers-optimized.php --post={slug} --category={category}

# AI mode: Gemini primary, OpenAI fallback on failure
php v2/scripts/blog/generate-faq-answers-optimized.php --post={slug} --category={category} --use-ai
```

**Output:** `data/faq-answers-optimized.json`

**AI fallback:** If Gemini fails or is unavailable, the script falls back to OpenAI when `OPENAI_API_KEY` is configured.

**Manual review per answer:**
- 40–80 words (target 55–65)
- Direct answer in first sentence
- Primary keyword in 3–5 FAQs (natural)
- Du tone, no template language ("Wichtig ist, dass...")
- 2–3 internal links total across all FAQs
- No AI content tells

### Step 6: Add FAQs to Post

```bash
php v2/scripts/blog/add-faqs-to-post.php --post={slug} --category={category}
```

If using a custom FAQ file:
```bash
php v2/scripts/blog/add-faqs-to-post.php --post={slug} --category={category} --faqs=docs/content/blog/posts/{category}/{slug}/data/faq-answers-optimized.json
```

To **replace** existing FAQs with improved answers (e.g. after lengthening or fixing links):
```bash
php v2/scripts/blog/add-faqs-to-post.php --post={slug} --category={category} --replace
```

### Step 7: Validation

```bash
php v2/scripts/blog/validate-faq-quality.php --post={slug} --category={category}
php v2/scripts/blog/validate-faq-schema.php --post={slug} --category={category}
php v2/scripts/blog/comprehensive-faq-analysis.php --post={slug} --category={category}
```

### Step 8: Browser Check

- Load: `http://localhost:8003/insights/{category}/{slug}/`
- Verify FAQ section renders correctly
- Optional: [Google Rich Results Test](https://search.google.com/test/rich-results) for schema

## Checklist Per Post

- [ ] Data collection complete (GSC, SISTRIX, faq-research)
- [ ] Keyword derivation run (and post updated if needed)
- [ ] Manual research reviewed (PAA, GSC queries, keywords)
- [ ] FAQ questions generated and manually curated
- [ ] FAQ answers generated and manually reviewed
- [ ] 10–15 FAQs added to post
- [ ] Schema validation passed
- [ ] Browser check passed

## Data Paths Reference

| Data | Path |
|------|------|
| GSC | `docs/content/blog/posts/{category}/{slug}/data/performance-gsc.json` |
| SISTRIX Keywords | `docs/content/blog/posts/{category}/{slug}/data/keywords-sistrix.json` |
| SERP Features | `docs/content/blog/posts/{category}/{slug}/data/serp-features.json` |
| FAQ Research | `docs/content/blog/posts/{category}/{slug}/data/faq-research.json` |
| FAQ Questions | `docs/content/blog/posts/{category}/{slug}/data/faq-questions.json` |
| FAQ Answers | `docs/content/blog/posts/{category}/{slug}/data/faq-answers-optimized.json` |

## Related Documentation

- [FAQ_CREATION_WORKFLOW_2026.md](FAQ_CREATION_WORKFLOW_2026.md) – Full creation workflow
- [FAQ_MANUAL_REVIEW_CHECKLIST.md](FAQ_MANUAL_REVIEW_CHECKLIST.md) – Per-FAQ quality checklist
- [FAQ_GAP_ANALYSIS_REPORT.md](FAQ_GAP_ANALYSIS_REPORT.md) – Current gap audit (regenerate with `audit-faq-gap-analysis.py`)
- [FAQ_GAP_REMEDIATION_PROGRESS.md](FAQ_GAP_REMEDIATION_PROGRESS.md) – Progress tracker

## Run Audit (Identify Gaps)

```bash
python3 v2/scripts/blog/audit-faq-gap-analysis.py
```

Output: `docs/content/blog/FAQ_GAP_ANALYSIS_REPORT.md` and `FAQ_GAP_ANALYSIS.json`