Create README.md

ProblemMap/GlobalDebugCardExamples/README.md

@@ -0,0 +1,99 @@
+# WFGY Global Debug Card · Example Cases
+
+This folder contains example inputs and outputs for the  
+**WFGY 3.0 · RAG 16 Problem Map – Global Debug Card**.
+
+It is dedicated to the Global Debug Card protocol and is separate from other ProblemMap example folders.
+
+The goal is simple:
+
+- provide minimal, well-documented failing cases
+- show before/after debug packets
+- make it easy to reproduce and compare repair loops
+
+## Folder structure
+
+Planned layout:
+
+- `cases/`  
+  Minimal failing cases expressed as `(Q, E, P, A)` plus optional metadata.
+
+- `packets/`  
+  Before/after debug packets generated by the protocol, following the JSON format from  
+  `ProblemMap/specs/wfgy_debug_packet_v1.json`.
+
+This keeps the human-facing card, the machine-readable specs, and the concrete examples clearly separated.
+
+## First demo case: retrieval off-topic
+
+Wave 0 will ship with one primary example:
+
+- `cases/retrieval_offtopic_case_v1.json`  
+  A failing case where the user question and the retrieved evidence are misaligned.  
+  The answer is confident but grounded in the wrong documents.
+
+It will be paired with two packets:
+
+- `packets/retrieval_offtopic_before_v1.json`  
+  Initial diagnosis before any repair, including detected type, modes, and suggested fixes.
+
+- `packets/retrieval_offtopic_after_v1.json`  
+  Diagnosis and outcome after one constrained repair loop has been applied and verified.
+
+Together, these three files form a complete, reproducible “before/after” story.
+
+## How this connects to Colab and specs
+
+This folder is designed to work together with:
+
+- Colab notebook:  
+  `ProblemMap/colab/wfgy_global_debug_card_colab_mvp.ipynb`
+
+- JSON specs:  
+  `ProblemMap/specs/wfgy_problem_catalog_v1.json`  
+  `ProblemMap/specs/wfgy_debug_packet_v1.json`
+
+Typical flow:
+
+1. Load one case from `cases/` into the Colab notebook.
+2. Run the triage and repair loop.
+3. Compare the notebook output with the corresponding packet in `packets/`.
+4. Optionally, write new packets back into this folder for future reference.
+
+This makes it easier to:
+
+- replay a known failure
+- compare different repair strategies
+- share reproducible examples with other teams
+
+## Scope for Wave 0
+
+Wave 0 will focus on examples that match the first supported modes:
+
+- No.1 retrieval wrong or off-topic
+- No.5 semantic vs embedding mismatch
+- No.8 missing evidence visibility
+- No.2 interpretation collapse
+
+More cases can be added later, but the first set should stay small and very clear.
+
+## Current status
+
+Work in progress.
+
+This folder is being prepared as the public example layer for the Global Debug Card protocol.  
+The initial case and packets will be added after the Colab MVP and JSON specs are stable enough to generate consistent outputs.
+
+## Related entry points
+
+Human-facing card and description:
+
+- `ProblemMap/wfgy-rag-16-problem-map-global-debug-card.md`
+
+Colab MVP landing page:
+
+- `ProblemMap/colab/README.md`
+
+Machine-readable specs:
+
+- `ProblemMap/specs/README.md`