42-passage-analyzer

name: 42-passage-analyzer description: > Passage-level content analyse voor AI/RAG readiness. Segmenteert pagina-content in passages (heading-boundary splitting), scoort elke passage op AI-extractability, en identificeert welke passages optimaal zijn voor citatie en welke herwerkt moeten. Optioneel AI-powered gap analyse per passage. Use when user says "passage analyse", "passage scoring", "chunk analyse", "RAG readiness", "AI extractability", "passage segmentatie", "content chunking". version: 1.0.0 tags: [seo, geo, passages, citability, rag, chunking, ai-readiness, content-analysis] allowed-tools:

• Bash
• Read
• Write
• Grep
• Glob
• WebFetch metadata: filePattern:
  • "**/passage"
  • "**/chunk"
  • "**/citab" bashPattern:
  • "passage"
  • "chunk"
  • "rag.ready"

Passage-Level Content Analyzer

Purpose

AI-zoekmachines citeren niet hele pagina's — ze citeren passages. Een passage van 134-167 woorden met een duidelijke claim, data, en zelfstandige context heeft de hoogste kans op citatie door ChatGPT, Perplexity en Google AI Overviews.

Deze skill segmenteert pagina-content in passages en scoort elke passage individueel op AI-extractability. Waar 42:citability op pagina-niveau scoort, werkt deze skill op passage-niveau — binnen een pagina.

Commands

# Heuristic modus (geen API nodig)
/42:passage-analyzer <url>                           # Analyseer enkele pagina
/42:passage-analyzer <sf-text-export-dir>            # Bulk analyse van SF text export
/42:passage-analyzer <url> --ai                      # Met AI gap-analyse per passage

# Embedding modus (echte cosine similarity vs target queries)
/42:passage-analyzer <url> --embeddings --queries gsc.csv --provider gemini
/42:passage-analyzer <sf-text-dir> --embeddings --queries keywords.csv --provider gemini
/42:passage-analyzer <sf-text-dir> --embeddings --queries gsc.csv --provider gemini --sf-embeddings sf-emb.csv

Twee scoring-modi

Heuristic is snel en gratis — goed voor structurele analyse ("is deze passage goed opgebouwd?"). Embeddings meet echte retrieval-kans — "voor welke queries zou een AI-zoekmachine deze passage citeren?"

In embedding-modus worden beide scores berekend: de heuristic score EN de retrieval score. Samen geven ze het volledige beeld: een passage kan structureel perfect zijn (hoge heuristic) maar irrelevant voor je target queries (lage retrieval), of andersom.

Input

Optie 1: URL (live fetch)

Pagina wordt opgehaald via WebFetch. Content wordt geëxtraheerd uit de HTML body (nav/header/footer/sidebar verwijderd).

Optie 2: Screaming Frog Text Export (aanbevolen voor bulk)

• Bulk Export > Web > All Page Text in SF
• Produceert één .txt bestand per pagina
• Schone body text, geen HTML parsing nodig

Optie 3: SF Internal:HTML Export + Content

• Internal:HTML CSV met URL, Title, H1, Meta Description
• Gecombineerd met All Page Text voor body content

Workflow

Stap 1: Content Extractie

Uit HTML (live fetch):

1. Verwijder: <script>, <style>, <nav>, <header>, <footer>, <aside>, .sidebar, .ads, .menu, .cookie
2. Behoud: <article>, <main>, <section>, <p>, <li>, <blockquote>, <h1>-<h6>, <table>
3. Extraheer tekst per element met HTML-tag type

Uit SF Text Export:

1. Lees .txt bestand per URL
2. Detecteer heading-patronen (regels in ALL CAPS of korte regels gevolgd door langere tekst)

Stap 2: Passage Segmentatie

Splits content in passages met deze regels:

Heading-boundary splitting:

• Elke H1/H2/H3 start een nieuwe passage
• De tekst tussen twee headings = één passage

Lengte-management:

• Als een passage >250 woorden is: splits op zin-grenzen
• Als een passage <50 woorden is: merge met volgende passage (tenzij het een heading-only sectie is)
• Target lengte: 134-167 woorden (optimale AI-citatie lengte)

Sliding window overlap:

• Bij splits: neem de laatste 30 woorden van de vorige passage mee als context-overlap
• Dit voorkomt dat zinnen uit context worden gerukt

Sectie-tracking:

• Elke passage krijgt een sectie-label (de heading erboven)
• Passages zonder heading = "Introduction" (voor eerste heading) of "Continuation"

Stap 3: Passage Scoring (0-100)

Elke passage wordt gescoord op 6 dimensies:

Score Interpretatie

Stap 4: Sectie-Analyse

Per sectie (H2-groep):

• Gemiddelde passage score
• Beste passage (meest citeerbaar)
• Slechtste passage (meest verbetering nodig)
• Passage count (te veel = sectie te lang, te weinig = te oppervlakkig)

Stap 5: AI Gap-Analyse (optioneel, --ai flag)

Stuur passage-metadata (niet volledige tekst) naar OpenAI/Anthropic:

Prompt structuur:

Analyseer deze pagina-passages voor AI-citatie optimalisatie:

[Per passage: id, sectie, woord-count, score, eerste 200 karakters]

Geef per passage:
1. Welke claim of feit een AI-systeem zou extraheren
2. Wat er ontbreekt voor een complete citatie (data? context? specificiteit?)
3. Concrete herschrijf-suggestie (max 2 zinnen)

Geef ook:
- Welke passages gemerged moeten worden (te kort, zelfde onderwerp)
- Welke passages gesplit moeten worden (te lang, meerdere onderwerpen)
- Welke secties een citation capsule missen (40-60 woord definitive statement)

Passage Semantische Gewichten

Passages erven een gewicht van hun HTML-context:

Gewicht wordt meegenomen als multiplier op de kwaliteitsscore voor prioritering, niet voor de score zelf.

Output Format

PASSAGE-ANALYSIS.md

# Passage Analysis — [URL/Domain]
Date: [Date]
Pages Analyzed: [Count]
Total Passages: [Count]

## Summary

| Metric | Waarde |
|--------|--------|
| Gemiddelde passage score | XX/100 |
| Passages ≥80 (excellent) | XX (XX%) |
| Passages 60-79 (good) | XX (XX%) |
| Passages 40-59 (needs work) | XX (XX%) |
| Passages <40 (poor/critical) | XX (XX%) |
| Gemiddelde passage lengte | XX woorden |
| Passages in optimaal bereik (134-167w) | XX (XX%) |

---

## Page: [URL]

### Passage Map

| # | Sectie | Woorden | Score | Lengte | Zelfst. | Data | Structuur | Lexicaal | Q&A | Preview |
|---|--------|---------|-------|--------|---------|------|-----------|----------|-----|---------|
| P01 | Introduction | 145 | 82 | 25 | 18 | 15 | 12 | 7 | 5 | "Screaming Frog SEO Spider is..." |
| P02 | How It Works | 178 | 71 | 20 | 16 | 10 | 13 | 8 | 4 | "The crawler starts by..." |
| P03 | How It Works | 92 | 38 | 8 | 10 | 5 | 8 | 5 | 2 | "It also checks for..." |

### Sectie Scores

| Sectie | Passages | Gem. Score | Beste | Slechtste |
|--------|----------|-----------|-------|-----------|
| Introduction | 1 | 82 | P01 (82) | P01 (82) |
| How It Works | 3 | 58 | P02 (71) | P03 (38) |

### Top Passages (meest citeerbaar)
1. **P01** (82/100) — "Screaming Frog SEO Spider is..." → Sterk: optimale lengte, data, zelfstandig
2. **P02** (71/100) — "The crawler starts by..." → Goed: iets te lang, weinig data

### Passages die Aandacht Nodig Hebben
1. **P03** (38/100) — "It also checks for..." → Probleem: te kort (92w), begint met "It also" (niet zelfstandig), geen data
   **Suggestie:** Merge met P02 of uitbreiden met specifieke voorbeelden en cijfers.

---

## AI Gap-Analyse (indien --ai)

### Merge Aanbevelingen
- P03 + P04: Zelfde onderwerp ("crawling process"), samen 188 woorden → optimaal als één passage

### Split Aanbevelingen
- P07 (312 woorden): Bevat twee onderwerpen ("indexability" en "canonicals") → splits op zin na "canonical tags"

### Ontbrekende Citation Capsules
- Sectie "Benefits": Geen enkele passage bevat een definitive 40-60 woord statement. Voeg toe na H2.
- Sectie "Pricing": Mist concrete prijsinformatie in citeerbaar formaat.

### Per-Passage Herschrijf-Suggesties
| Passage | Huidige Opening | Suggestie |
|---------|----------------|-----------|
| P03 | "It also checks for..." | "Screaming Frog validates 15 technical SEO elements including..." |
| P05 | "This is important because..." | "Sites with broken canonical tags lose an average of 23% organic traffic..." |

Embedding Modus — Retrieval Scoring

Wat het doet

In embedding-modus wordt elke passage als vector geëmbed (via Gemini) en vergeleken met target queries via cosine similarity. Dit geeft een echte retrieval score: hoe waarschijnlijk is het dat een AI-zoekmachine deze passage citeert als antwoord op een specifieke query?

Input voor embedding-modus

Workflow

# 1. Segmenteer passages (zelfde als heuristic)
# 2. Embed elke passage-tekst via API
python3 scripts/passage_analyzer.py \
    --sf-text-dir ./sf-text-export/ \
    --embeddings \
    --queries gsc-performance-export.csv \
    --provider gemini \
    --model text-embedding-004 \
    --output analysis.json

Retrieval Score Interpretatie

Output Voorbeeld (embedding modus)

Per passage worden beide scores gerapporteerd:

| # | Sectie | Woorden | Heuristic | Retrieval | Best Match Query | Similarity |
|---|--------|---------|-----------|-----------|-----------------|-----------|
| P01 | Introduction | 145 | 82/100 | 87/100 | "seo audit tool" | 0.87 |
| P02 | How It Works | 178 | 71/100 | 42/100 | "website crawler" | 0.42 |
| P03 | Pricing | 92 | 38/100 | 91/100 | "screaming frog price" | 0.91 |

Insight uit het voorbeeld:

• P01: Hoog op beide → perfecte passage, niet aanpassen
• P02: Goede structuur maar lage retrieval → structureel goed geschreven maar beantwoordt geen target query. Herformuleer richting een specifiek keyword.
• P03: Lage structuur maar hoge retrieval → slordig geschreven maar AI's willen het citeren. Investeer in betere structuur.

Kosten Schatting

Kosten zijn minimaal — Gemini text-embedding-004 heeft een gratis tier en kost daarna ~$0.075 per 1M tokens.

Vergelijking: Heuristic vs Embedding

Integratie met 42: Suite

Cross-References

• Voor pagina-niveau citability scoring → /42:citability
• Voor passage herschrijving → /42:genai-optimizer
• Voor content quality + E-E-A-T → /42:content
• Voor Screaming Frog text export → /42:screaming-frog export <url> --tab "Content:All"
• Voor blog-specifieke citability → /42:blog-geo