WFGY/ProblemMap/BeginnerGuide.md

🆕 Beginner Guide — How to Identify & Fix Your AI Failure

A zero-to-hero crash-course for anyone new to WFGY, RAG pipelines, or “why is my model hallucinating?”

If the full Problem Map feels overwhelming, start here.
In ~10 minutes you’ll locate your failure family, run a safe first fix, and know how to verify it.

---

Quick Nav
Getting Started (Practical) · Problem Map 2.0 (RAG) · Patterns Index · Examples · Eval · Ops

---

0) 🎯 Why this guide exists

When RAG breaks, it’s rarely one bug. It’s stacked illusions across OCR → chunking → embedding → retrieval → prompt → reasoning.
This guide helps you:

1. Identify the failure family fast
2. Apply the minimal structural fix (not prompt band-aids)
3. Verify with objective signals: ΔS (semantic stress), λ_observe (layered states), E_resonance (coherence)

Then jump deeper via Problem Map 2.0 and Patterns.

---

1) 🔍 “Which symptom matches my bug?”

Follow the first Yes you hit; then open that page.

Question	Yes → Open	No → Next
Chunks look correct but the answer is wrong?	hallucination.md	↓
Reached the right chunk but logic fails?	retrieval-collapse.md	↓
Multi-step tasks derail after a few hops?	context-drift.md	↓
Model gives confident nonsense?	bluffing.md	↓
High similarity scores but wrong meaning?	embedding-vs-semantic.md	↓
Logic dead-ends / loops?	logic-collapse.md	↓
Long chat forgets context?	memory-coherence.md	↓
Can’t trace why it failed?	retrieval-traceability.md	↓
Output becomes incoherent / repetitive?	entropy-collapse.md	↓
Replies turn flat / literal?	creative-freeze.md	↓
Formal/symbolic prompts break?	symbolic-collapse.md	↓
Paradox/self-reference crashes?	philosophical-recursion.md	↓
Multi-agent roles/memory collide?	multi-agent-chaos.md	↓
Tools fire before index/data ready?	bootstrap-ordering.md	↓
Services wait on each other forever?	deployment-deadlock.md	↓
First prod call crashes after deploy?	predeploy-collapse.md	File an Issue →

Extended patterns (very common in the wild):

• Hybrid HyDE+BM25 gets worse than single → patterns/pattern_query_parsing_split.md
• Two sources merge into one (who-said-what mixes) → patterns/pattern_symbolic_constraint_unlock.md
• You correct it, bad fact returns later → patterns/pattern_hallucination_reentry.md
• State flips across tabs/sessions → patterns/pattern_memory_desync.md
• Some facts won’t retrieve though indexed → patterns/pattern_vectorstore_fragmentation.md
• RAG boots but tools fire too early → patterns/pattern_bootstrap_deadlock.md

Still unsure? Capture a minimal trace (input → retrieved snippets → answer) and run ΔS/λ checks (Section 3). Post in Discussions if needed.

---

2) 🧠 Core concepts in <5 minutes

2.1 What is RAG?

raw docs → ocr/parsing → chunking → embeddings → vector store
→ retriever → prompt assembly → LLM reasoning/tools

• Perception drift upstream hides logic drift downstream. Fix structure, not style.

2.2 Embedding scores vs. meaning

Cosine proximity ≠ human semantics. WFGY’s ΔS = 1 − cos(I, G) uses grounded anchors to catch real meaning gaps.

2.3 Layered observability (λ_observe)

States: → convergent · ← divergent · <> recursive · × chaotic.
If upstream is stable but downstream flips, the boundary between them is failing.

2.4 WFGY repair operators (cheat-sheet)

Operator	What it does (1-liner)
BBMC	Minimize semantic residue to re-align with anchors
BBPF	Explore safe alternate paths; avoid dead-end chains
BBCR	Detect collapse; insert bridge node; rebuild reasoning
BBAM	Modulate attention variance; prevent entropy melt

---

3) 🛠️ Run your first fix (3 minutes)

1. Download the assets below, or jump to Getting Started for a runnable pipeline.
2. Paste TXT OS into your model chat.
3. Ask:

I’ve loaded TXT OS. Diagnose my RAG:

* symptom: \[describe]
* trace: \[question, retrieved snippet(s), answer]
  Using WFGY, tell me:

1. failing layer & why (ΔS/λ),
2. the Problem Map page to open,
3. minimal steps to push ΔS ≤ 0.45 and keep λ convergent,
4. how to verify with a reproducible test.

Triage thresholds (keep these handy):

• ΔS: <0.40 stable · 0.40–0.60 transitional (record if λ ∈ {←, <>}) · ≥0.60 high-risk (act)
• Acceptance: ΔS(question, context) ≤ 0.45, λ convergent, E_resonance flat

---

4) 🗂️ Problem categories (cheat-labels)

Category	Typical stage	Open first
Retrieval	Vector DB, search, chunking	hallucination.md · embedding-vs-semantic.md
Reasoning	Mid-chain logic	retrieval-collapse.md · logic-collapse.md
Patterns	High-frequency edge cases	patterns/README.md
Eval	Measure & guard regressions	eval/README.md
Ops	Boot order, runbooks	ops/README.md

---

5) ✅ Verify the repair (don’t skip)

• Retrieval sanity: ≥ 70% token overlap with target section; ΔS(question, context) ≤ 0.45 → see eval/eval_rag_precision_recall.md
• Reasoning stability: λ stays convergent on 3 paraphrases; E_resonance flat → see eval/eval_semantic_stability.md
• Latency vs accuracy: chart ΔS vs p95 latency → see eval/eval_latency_vs_accuracy.md

---

6) 🙋 FAQ (super short)

Question	Answer
Do I need all operators?	No. Use the one named on the matching page.
Does WFGY replace LangChain/LlamaIndex?	No. It sits above them as a reasoning firewall.
Will this work on small models?	Yes; #11/#12 are easier on GPT-4-class or strong local models.
Where are runnable examples?	Start here: examples/README.md and example_01_basic_fix.md.

---

7) 📥 Download links (60 sec)

Asset	Link
WFGY 1.0 PDF	https://zenodo.org/records/15630969
TXT OS (plain-text)	https://zenodo.org/records/15788557

MIT-licensed. Copy, ship, and adapt.

---

🧭 Explore More

Module	Description	Link
WFGY Core	Standalone semantic reasoning engine for any LLM	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 →

---

👑 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