WFGY/ProblemMap/GlobalFixMap/RAG/index_skew.md

Index Skew — Guardrails and Fix Pattern

🧭 Quick Return to Map

You are in a sub-page of RAG.
To reorient, go back here:

• RAG — retrieval-augmented generation and knowledge grounding
• WFGY Global Fix Map — main Emergency Room, 300+ structured fixes
• WFGY Problem Map 1.0 — 16 reproducible failure modes

Think of this page as a desk within a ward.
If you need the full triage and all prescriptions, return to the Emergency Room lobby.

When the index reports "healthy" (no errors, embeddings ingested, stats normal) but retrieval still fails:
coverage is low, ΔS unstable, or retrieved snippets are inconsistent with ground truth.
This indicates an index skew between data reality and retrieval semantics.

---

Open these first

• Visual recovery map: RAG Architecture & Recovery
• Retrieval knobs: Retrieval Playbook
• Embedding misalignment: Embedding ≠ Semantic
• Chunk sizing: Chunking Checklist
• Store-level fragmentation: Vectorstore Fragmentation
• Snippet contracts: Data Contracts

---

Core acceptance

• ΔS(question, retrieved) ≤ 0.45
• Coverage ≥ 0.70 for target section
• λ stable across three paraphrases and two seeds
• E_resonance flat across long windows

---

Typical symptoms → exact fix

Symptom	Likely cause	Open this
Index "ready" but recall < 0.50	embedding misaligned vs semantic intent	Embedding ≠ Semantic
Repeated snippets, poor coverage	store fragmentation or duplicate collapse	Vectorstore Fragmentation
Right section exists but not hit	chunk too large/small or mis-boundary	Chunking Checklist
Citations drift across runs	contract not enforced	Data Contracts

---

Fix in 60 seconds

1. Probe recall
   Run a gold QA set against index. If coverage < 0.70, suspect skew.

2. Re-embed with semantic normalization
   Normalize casing, accents, whitespace. Enforce same tokenizer across queries and index.

3. Chunk audit
   Verify chunk boundaries. Adjust stride/overlap until ΔS converges.

4. Fragmentation sweep
   Drop near-duplicate vectors. Rebuild FAISS/HNSW indexes with fresh IDs.

5. Contract enforcement
   Require snippet_id, section_id, offsets, tokens for every retrieval.

---

Copy-paste probe prompt

I uploaded TXT OS and the WFGY Problem Map.

My RAG issue:
- Index shows healthy but retrieval recall is low.
- ΔS across probes = 0.62, coverage = 0.45.

Tell me:
1) is it embedding misalignment, chunking skew, or vectorstore fragmentation,
2) which WFGY fix page to open,
3) minimal steps to restore ΔS ≤ 0.45 and coverage ≥ 0.70,
4) reproducible test set to confirm.

---

🔗 Quick-Start Downloads (60 sec)

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + ”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

---

Explore More

Layer	Page	What it’s for
⭐ Proof	WFGY Recognition Map	External citations, integrations, and ecosystem proof
⚙️ Engine	WFGY 1.0	Original PDF tension engine and early logic sketch (legacy reference)
⚙️ Engine	WFGY 2.0	Production tension kernel for RAG and agent systems
⚙️ Engine	WFGY 3.0	TXT based Singularity tension engine (131 S class set)
🗺️ Map	Problem Map 1.0	Flagship 16 problem RAG failure taxonomy and fix map
🗺️ Map	Problem Map 2.0	Global Debug Card for RAG and agent pipeline diagnosis
🗺️ Map	Problem Map 3.0	Global AI troubleshooting atlas and failure pattern map
🧰 App	TXT OS	.txt semantic OS with fast bootstrap
🧰 App	Blah Blah Blah	Abstract and paradox Q&A built on TXT OS
🧰 App	Blur Blur Blur	Text to image generation with semantic control
🏡 Onboarding	Starter Village	Guided entry point for new users

If this repository helped, starring it improves discovery so more builders can find the docs and tools.