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

Module	Description	Link
WFGY Core	Canonical framework entry point	View
Problem Map	Diagnostic map and navigation hub	View
Tension Universe Experiments	MVP experiment field	View
Recognition	Where WFGY is referenced or adopted	View
AI Guide	Anti-hallucination reading protocol for tools	View

If this repository helps, starring it improves discovery for other builders.