WFGY/ProblemMap/Diagnose.md

🩺 Semantic Failure Diagnostic Sheet

Select the symptom(s) you observe.
Each entry links to the corresponding solution page in the WFGY Problem Map.
🧩 Prefer runnable examples? MVP Demos → ProblemMap/mvp_demo/README.md

---

Quick Nav

Problem Map 1.0 · RAG Problem Map 2.0 · Semantic Clinic Index · Retrieval Playbook · Rerankers · Data Contracts · Multilingual Guide · Privacy & Governance

---

Core 16 failures

#	Symptom	Problem ID	Solution
1	Retriever returns wrong/irrelevant chunks; citations miss expected section	#1 Hallucination & Chunk Drift	hallucination.md
2	Correct chunks are present, but reasoning is wrong	#2 Interpretation Collapse	retrieval-collapse.md
3	Multi-step tasks drift off-topic after a few hops	#3 Long Reasoning Chains	context-drift.md
4	Model answers confidently with made-up facts	#4 Bluffing / Overconfidence	bluffing.md
5	High cosine similarity but meaning is wrong	#5 Semantic ≠ Embedding	embedding-vs-semantic.md
6	Logic dead-ends; retries loop or reset nonsense	#6 Logic Collapse & Recovery	logic-collapse.md
7	Long conversation: model forgets previous context	#7 Memory Breaks Across Sessions	memory-coherence.md
8	Pipeline is opaque; unable to trace “why this snippet”	#8 Debugging is a Black Box	retrieval-traceability.md
9	Attention melts; output incoherent or repetitive	#9 Entropy Collapse	entropy-collapse.md
10	Responses become flat, literal, lose creativity	#10 Creative Freeze	creative-freeze.md
11	Formal/symbolic prompts break the model	#11 Symbolic Collapse	symbolic-collapse.md
12	Self-reference / paradox crashes reasoning	#12 Philosophical Recursion	philosophical-recursion.md
13	Multiple agents overwrite or misalign logic (overview)	#13 Multi-Agent Chaos	Multi-Agent_Problems.md
14	System runs but outputs nothing; boot order off	#14 Bootstrap Ordering	bootstrap-ordering.md
15	System never reaches expected state; actions stall	#15 Deployment Deadlock	deployment-deadlock.md
16	First prod call after deploy crashes / “empty logic”	#16 Pre-Deploy Collapse	predeploy-collapse.md

---

Extended patterns (targeted fixes)

Pattern	When to use	Fix page
Rerankers (ordering control)	Recall seems fine but top-k ordering is messy	rerankers.md
Retrieval Playbook (end-to-end knobs)	You want a guided checklist across retriever params	retrieval-playbook.md
Query Parsing Split	HyDE/BM25 hybrid worse than single retriever	patterns/pattern_query_parsing_split.md
Symbolic Constraint Unlock (SCU)	“Who said what” merges across sources; cross-bleed	patterns/pattern_symbolic_constraint_unlock.md
Hallucination Re-entry	You correct the model, but the wrong claim returns	patterns/pattern_hallucination_reentry.md
Vectorstore Fragmentation	Some facts can’t be retrieved though indexed	patterns/pattern_vectorstore_fragmentation.md
Memory Desync	Tabs/sessions flip between old/new facts	patterns/pattern_memory_desync.md
Bootstrap Deadlock (RAG boot fence)	Tools fire before data/index is ready	patterns/pattern_bootstrap_deadlock.md
Data Contracts	Need a standard schema for snippets/citations	data-contracts.md
Multilingual Guide	Non-English corpora drift / tokenizer mismatch	multilingual-guide.md
Privacy & Governance	PII/compliance concerns for traces/logs	privacy-and-governance.md

---

Minimal triage rules

• Measure first:
  • ΔS(question, retrieved_context) = 1 − cosθ
  • High risk if ΔS ≥ 0.60; investigate if 0.40–0.60 and λ ∈ {←, <>}.
• Accept when: ΔS ≤ 0.45 · λ stays convergent (→) on ≥3 paraphrases · E_resonance flat.
• Coverage sanity: retrieved tokens vs target section ≥ 0.70 for direct QA.

👉 Not sure where it fits? Run ΔS / λ_observe first, or use the MVP demos for quick diagnosis: python ProblemMap/mvp_demo/main.py (run from repo root)

---

🔗 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

Layer	Page	What it’s for
Proof	WFGY Recognition Map	External citations, integrations, and ecosystem proof
Engine	WFGY 1.0	Original PDF based tension engine
Engine	WFGY 2.0	Production tension kernel and math engine for RAG and agents
Engine	WFGY 3.0	TXT based Singularity tension engine, 131 S class set
Map	Problem Map 1.0	Flagship 16 problem RAG failure checklist and fix map
Map	Problem Map 2.0	RAG focused recovery pipeline
Map	Problem Map 3.0	Global Debug Card, image as a debug protocol layer
Map	Semantic Clinic	Symptom to family to exact fix
Map	Grandma’s Clinic	Plain language stories mapped to Problem Map 1.0
Onboarding	Starter Village	Guided tour for newcomers
App	TXT OS	TXT semantic OS, fast boot
App	Blah Blah Blah	Abstract and paradox Q and A built on TXT OS
App	Blur Blur Blur	Text to image with semantic control
App	Blow Blow Blow	Reasoning game engine and memory demo

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