# Content Depth Validation Guide

**Last Updated:** 2026-03-18

When to run `validate-section-depth.php` and `validate-content-completeness.php`, and how to fix failures. These scripts are mandatory before finalizing new blog posts.

## When to Run

- **New post creation:** Run both before publishing (step 6 in blog-new-post-creation workflow)
- **Content expansion:** After expanding content-draft.html and running `update-post-content.php`
- **Pre-deploy:** As part of validation gates for lexikon/ratgeber posts

## Scripts Overview


| Script                               | Purpose                                                                                                                                                                                       | Exit 0                  | Exit 1                       |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------- |
| `validate-section-depth.php`         | Each H2 has 2+ paragraphs or 1 paragraph + list/table; with `--check-h3`: each H3 has ≥2 sentences or list/table                                                                              | All sections meet depth | One or more thin H2 sections |
| `validate-content-completeness.php`  | PAA covered, content gaps addressed, definition in first 20%                                                                                                                                  | Complete                | Expand needed                |
| `validate-content-flow.php`          | Definition placement, FAQ separation, heading hierarchy, **paragraph length** (flags paragraphs >80 words), **term-definition pairs** (flags paragraphs with 2+ `Term:` or `Für X:` patterns) | No issues               | —                            |
| `compare-content-to-competitors.php` | Word count, H2/H3 structure, formats vs top competitors; content gaps                                                                                                                         | PASS/WARN (exit 0)      | —                            |


**compare-content-to-competitors.php** compares your post to top competitors on word count, H2/H3 counts, formats (tables, lists), and content gaps. Run after content draft and before finalizing. See [CONTENT_CREATION_WORKFLOW_2026.md](CONTENT_CREATION_WORKFLOW_2026.md).

## Running the Scripts

```bash
php v2/scripts/blog/validate-section-depth.php --post=slug --category=lexikon [--check-h3]
php v2/scripts/blog/validate-content-completeness.php --post=slug --category=lexikon
php v2/scripts/blog/compare-content-to-competitors.php --post=slug --category=lexikon
```

**Options for validate-section-depth:**

- `--check-h3` – Also validate H3 depth (≥2 sentences or list/table per H3). Thin H3s are reported as warnings; does not affect exit code. Per [CONTENT_DEPTH_GUIDELINES.md](CONTENT_DEPTH_GUIDELINES.md): "Minimum H3 depth: Each H3 should have ≥2 sentences or a list/table."

**Options for validate-content-completeness:**

- `--check-redundancy` – Also run H2–FAQ overlap check (informational)
- `--min-word-ratio=N` – Minimum word count as fraction of outline target (default: 0.8). Warns if content < 80% of target.

## Fixing validate-section-depth Failures

**Failure:** "THIN SECTIONS – needs 2+ paragraphs" or "needs list or table"

**Fix:**

1. Edit `docs/content/blog/posts/{category}/{slug}/content-draft.html`
2. For each thin H2 section:
  - **Option A:** Add a second paragraph with substantive content (examples, details, implications)
  - **Option B:** Add a list (`<ul>`/`<ol>`) or table (`<table>`) with 1 paragraph
3. Run `update-post-content.php` to push changes to post JSON
4. Re-run `validate-section-depth.php`

**Example:** If "Merkmale der Generation Alpha" has only 1 paragraph, add a bullet list of key traits or a second paragraph with concrete examples.

### Thin H3 Sections (with --check-h3)

**Warning:** "Thin H3 (1 sentence, no list/table): …"

**Fix:** Per CONTENT_DEPTH_GUIDELINES, each H3 should have ≥2 sentences or a list/table. Add a second sentence with context, example, or implication; or convert to a list if the content is itemized.

**H3 decisions:** Based on structure and TOC value, not word count. Use H3 when 3+ distinct subtopics, Vor-/Nachteile, Formen/Arten, or PAA/featured-snippet potential justify subdivision. See [CONTENT_DEPTH_GUIDELINES.md](CONTENT_DEPTH_GUIDELINES.md) and [HEADING_HIERARCHY_GUIDE.md](HEADING_HIERARCHY_GUIDE.md).

## Fixing validate-content-completeness Failures

**Failure types:**

### PAA Not Covered

**Fix:** Either add the PAA topic to an H2 section in content-draft.html, or add it as an FAQ. Run `check-h2-faq-overlap.php` to avoid FAQ–H2 redundancy.

### Content Gaps Not Addressed

**Fix:** Review `competitive-depth-analysis.md` content gaps. Add sections or paragraphs that address the missing topics. No filler—add substantive value.

### Format Recommendations Missing

**Fix:** If competitive-depth recommends tables or lists, add them. Tables for comparisons; lists for step-by-step or key points.

### Definition Not in First 20%

**Fix:** Move or add the core definition (Was ist…?) within the first 20% of the content. The definition should appear before lengthy background.

### Word Count Below Outline Target

**Fix:** Expand thin sections or add missing topics. Target: ≥ 80% of outline word count (configurable via `--min-word-ratio`). Do not add filler.

### Fazit Missing (lexikon)

**Fix:** Add H2 Fazit (or Zusammenfassung) before "Stand der Angaben: …". Write 2–3 sentences summarizing key points without copying the intro. May include Ordio product mention.

### Inline (1)(2)(3) in Paragraph

**Fix:** Replace inline numbering like "(1) … (2) … (3) …" in a single paragraph with an ordered list: `<ol><li>…</li><li>…</li></ol>`. See [CONTENT_DEPTH_GUIDELINES.md](CONTENT_DEPTH_GUIDELINES.md) Numbered Steps.

### Long Paragraphs (validate-content-flow.php)

**Warning:** "Long paragraphs (aim for 2-3 sentences, max ~80 words): N found"

**Fix:** Split paragraphs with >80 words into 2–3 shorter paragraphs. Best practice per shared-patterns: 2–3 sentences per paragraph for readability. Run `validate-content-flow.php --post=slug --category=category` to check.

### Multiple Term-Definition Pairs in One Paragraph (validate-content-flow.php)

**Warning:** "Multiple term-definition pairs in one paragraph (use bullet list or separate paragraphs): N found"

**Fix:** Refactor paragraphs that contain 2+ `**[term]**: definition` or `Für X: definition` patterns into:

- **Bullet list** (`<ul><li><strong>Term</strong>: Definition</li>...</ul>`) – preferred for 2–5 related terms
- **Separate paragraphs** – when each term needs 2+ sentences
- **Table** – when comparing 3+ terms with similar structure

See [CONTENT_STRUCTURE_FORMATTING_GUIDE.md](../CONTENT_STRUCTURE_FORMATTING_GUIDE.md#term-definition-patterns-multiple-terms-in-one-block).

## Phase Gate

Do not publish until both scripts pass. Warnings from `validate-content-completeness` (e.g. word count below target) should be addressed when possible; errors (PAA uncovered, thin sections) block publication.

## Related Documentation

- [CONTENT_DEPTH_GUIDELINES.md](CONTENT_DEPTH_GUIDELINES.md) – Depth levels and expand vs stop
- [BLOG_POST_IMPROVEMENT_PROCESS.md](BLOG_POST_IMPROVEMENT_PROCESS.md) – New post creation workflow