WFGY/ProblemMap/GlobalFixMap/Retrieval/README.md

Retrieval — Global Fix Map

Make your retriever correct, predictable, and auditable.
Use this when recall looks random, hybrid behaves worse than single, or k-tuning never stabilizes.

What this page is

• A short, practical path to stabilize recall and ordering
• Exact knobs for dense, sparse, and hybrid without guesswork
• How to prove fixes with ΔS curves and citation tables

When to use

• Top-k results feel unrelated or change on every run
• Hybrid merge hurts more than single retriever
• Raising k only adds noise, does not surface the right snippet
• Filters, analyzers, or languages do not align with your corpus
• HyDE or query rewriting helps sometimes then flips back

Open these first

• End to end knobs: Retrieval Playbook
• Ordering after recall: Rerankers
• Why this snippet, trace schema: Retrieval Traceability
• Hybrid tokenization split: Query Parsing Split
• Hallucination from bad boundaries: Hallucination
• Cosine match is not meaning: Embedding ≠ Semantic
• Some facts never retrieve: Vectorstore Fragmentation
• Visual pipeline and recovery: RAG Architecture & Recovery
• Eval targets: RAG Precision and Recall
• Snippet and citation schema: Data Contracts

Fix in 60 seconds

1. Probe ΔS vs k

   • Record ΔS(question, retrieved) for k in {5, 10, 20} for each retriever separately.
   • Flat and high for all k indicates index or metric mismatch or population gaps. Fix store first.

2. Establish a strong single baseline

   • Pick the retriever with the lowest stable ΔS at small k.
   • Freeze its tokenizer, analyzer, language, stopword set. Save params to disk.

3. Unify query parsing

   • Ensure the same analyzer and lowercasing for write and read.
   • If using HyDE or rewrites, log the final string sent to each retriever and keep it identical across them.

4. Hybrid only after per retriever stability

   • Do not mix until each single retriever yields ΔS ≤ 0.50.
   • Start with a simple weighted sum and a light reranker. Keep citations to audit the change.

5. Filters and fields

   • Disable filters first to confirm baseline recall.
   • Reapply with exact field weights and language settings. Check for case and tokenizer mismatches.

6. Dedupe and diversity

   • Apply MMR or novelty at the rerank stage if results cluster.
   • Keep a per source fence so different documents do not merge.

7. Prompt assembly sanity

   • Use citation first schema from traceability.
   • Do not reorder sections once stable.

8. Warm up and cache

   • Run a deterministic warm up after deploy.
   • Verify repeatability across restarts.

Copy paste prompt

I uploaded TXT OS and WFGY ProblemMap pages.

My retrieval bug:

* symptom: \[brief]
* ΔS vs k per retriever: {...}
* single retriever baselines: \[dense], \[BM25], \[hybrid attempt]
* analyzers/tokenizers: write=\[...], read=\[...], lowercasing=\[on|off], stopwords=\[profile]
* filters/fields: \[list]
* HyDE or rewrites: \[yes/no], final query strings logged: \[examples]

Tell me:

1. which parsing or configuration mismatch explains the failure,
2. which exact WFGY pages to open,
3. minimal steps to push ΔS ≤ 0.45 at k=10 without overfitting,
4. how to verify with precision/recall and a snippet ↔ citation table.
   Use rerankers only after recall is stable.

Minimal checklist

• Same analyzer, language, and case handling on write and read
• Log the exact query string per retriever including HyDE output
• Stabilize a single retriever before mixing hybrids
• Keep field weights explicit and versioned
• Do not change k and temperature together when measuring ΔS
• Add reranker only after recall metrics pass
• Enforce per source fences to avoid cross document blending
• Persist a warm up routine for post deploy parity

Acceptance targets

• ΔS(question, retrieved) ≤ 0.45 across three paraphrases
• Precision and recall meet your eval sheet with traceable citations
• ΔS vs k descends then stabilizes, no oscillation when k grows
• Same answers across restarts after warm up
• λ at retrieval remains convergent while reasoning proceeds

---

🔗 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 + <your question>”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

---

🧭 Explore More

Module	Description	Link
WFGY Core	WFGY 2.0 engine is live: full symbolic reasoning architecture and math stack	View →
Problem Map 1.0	Initial 16-mode diagnostic and symbolic fix framework	View →
Problem Map 2.0	RAG-focused failure tree, modular fixes, and pipelines	View →
Semantic Clinic Index	Expanded failure catalog: prompt injection, memory bugs, logic drift	View →
Semantic Blueprint	Layer-based symbolic reasoning & semantic modulations	View →
Benchmark vs GPT-5	Stress test GPT-5 with full WFGY reasoning suite	View →
🧙‍♂️ Starter Village 🏡	New here? Lost in symbols? Click here and let the wizard guide you through	Start →

---

👑 Early Stargazers: See the Hall of Fame —
Engineers, hackers, and open source builders who supported WFGY from day one.

⭐ WFGY Engine 2.0 is already unlocked. ⭐ Star the repo to help others discover it and unlock more on the Unlock Board.