WFGY/ProblemMap/SemanticClinicIndex.md

🏥 Semantic Clinic Index

A complete triage hub for AI failures — beyond the core 16 — powered by WFGY.
Use this page when you don’t yet know which thing is breaking. Start from symptoms, jump to a failure family, then open the exact fix page. All fixes are driven by WFGY instruments: ΔS (semantic stress), λ_observe (layered observability), and E_resonance (coherence control).

If this page saves you time, a ⭐ helps others find it.

---

How to use this page

1. Identify the symptom in the table below.
2. Open the family (Prompting / Retrieval / Reasoning / Memory / Agents / Infra / Eval).
3. Follow the fix page, then verify with ΔS ≤ 0.45 and convergent λ.

Prefer a pipeline-first view (OCR → chunk → embed → store → retrieve → prompt → LLM)?
Read RAG Architecture & Recovery.

---

Want to explore all failure types or test fixes directly?

→ See the full Problem Map Index for categorized issues and fixes.

---

Quick triage by symptom

Symptom you see	Likely family	Open this
Answers cite wrong snippet / mismatch with ground truth	Retrieval → RAG	hallucination.md
Chunks look right but reasoning is wrong	Reasoning	retrieval-collapse.md
High similarity, wrong meaning	Retrieval / Embeddings	embedding-vs-semantic.md
Model can’t explain why (no trace)	Observability	retrieval-traceability.md
Output collapses over long dialogs / 100 k tokens	Memory / Long-context	long-context-stress.md
Jailbreak or prompt injection succeeds	Prompting / Safety	prompt-injection.md
Vector store index “looks fine” but retrieval irrelevant	Retrieval / Data	vectorstore-metrics-and-faiss-pitfalls.md
OCR PDFs look correct yet answers drift	Data / OCR	ocr-parsing-checklist.md
Multi-agent tools fight each other	Agents	multi-agent-chaos.md
First prod call crashes after deploy	Infra / Boot	predeploy-collapse.md

Still lost? Open the Beginner Guide symptom checklist first.

---

Families & maps (with exact fixes)

A) Prompting & Safety

Guard against injections, jailbreaks, role drift, and schema leakage.

• Prompt Injection — prompt-injection.md
• System Prompt Drift — system-prompt-drift.md
• Citation-first, schema-locked prompting — retrieval-traceability.md
• Overconfidence / Bluffing Controls — bluffing.md
• Safety Boundary Map (overview) — Safety_Boundary_Problems.md

Verification: ΔS(question, context) ≤ 0.45; λ remains convergent across paraphrases; injection probes do not flip λ.

---

B) Retrieval, Data & Vector Stores

Make the index correct, measured, and explainable.

• Hallucination & Chunk Drift — hallucination.md
• Interpretation vs Retrieval Collapse — retrieval-collapse.md
• Embedding ≠ Semantic Meaning — embedding-vs-semantic.md
• Traceability (why this snippet?) — retrieval-traceability.md
• Vector Store Metrics & FAISS Pitfalls — vectorstore-metrics-and-faiss-pitfalls.md
• Semantic Chunking Checklist — chunking-checklist.md
• OCR / Parsing Quality Gate — ocr-parsing-checklist.md

Verification: coverage ≥ 0.70 to target section; ΔS(question, retrieved) ≤ 0.45; flat-high ΔS vs k ⇒ index/metric mismatch.

---

C) Reasoning & Logic Control

Detect and repair logic collapse, dead ends, and abstraction failures.

• Logic Collapse & Recovery — logic-collapse.md
• Long Reasoning Chains — context-drift.md
• Symbolic Collapse — symbolic-collapse.md
• Philosophical Recursion — philosophical-recursion.md
• Reasoning Schemas (cite → explain, bridge nodes) — reasoning-schemas.md
• Tool Router Debug — tool-router-debug.md

Verification: fix point when λ stays convergent after applying BBCR (bridge) + BBAM (variance clamp).

---

D) Memory & Long-Context

Keep threads coherent across sessions and very long windows.

• Memory Breaks Across Sessions — memory-coherence.md
• Entropy Collapse — entropy-collapse.md
• Long-Context Stress Map — long-context-stress.md
• Conversation Stitching & Memory Design — memory-design-patterns.md

Verification: E_resonance flat; ΔS stable at window joins.

---

E) Multi-Agent & Orchestration

Coordinate tools, roles, and shared memory without conflict.

• Multi-Agent Chaos — multi-agent-chaos.md
• Agent Boundary Design — agent-boundary-design.md
• Consensus Protocols for Agents — agent-consensus-protocols.md

Verification: when agents couple, ΔS does not spike; arbitration logs traceable.

---

F) Infra / Deploy

Boot in a known-good order, every time.

• Bootstrap Ordering — bootstrap-ordering.md
• Deployment Deadlock — deployment-deadlock.md
• Pre-Deploy Collapse — predeploy-collapse.md
• Observability Runbook — observability-runbook.md

Verification: deterministic warm-up; idempotent index builds; version/secret checks pass.

---

G) Evaluation & Guardrails

Detect “double hallucination” and prevent regression.

• Evaluation Playbook — evaluation-playbook.md
• WFGY Metrics Spec — wfgy-metrics.md

Acceptance: retrieve QA coverage ≥ 0.70 and ΔS ≤ 0.45; λ convergent; repeatability across seeds.

---

Ask the AI to fix your AI (safe prompt)

Read the WFGY TXT OS and Problem Map docs. Extract ΔS, λ_observe, E_resonance and the modules (BBMC, BBPF, BBCR, BBAM).
Given my failure:

- symptom: [describe]
- traces: [ΔS probes, λ states if any]

Tell me:
1) which layer/family is failing and why,
2) which fix page to open,
3) minimal steps to push ΔS ≤ 0.45 and keep λ convergent,
4) how to verify the fix.

---

🧭 Explore More

Module	Description	Link
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 →

---

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

⭐ Help reach 10,000 stars by 2025-09-01 to unlock Engine 2.0 for everyone ⭐ Star WFGY on GitHub