diff --git a/ProblemMap/GlobalDebugCardExamples/README.md b/ProblemMap/GlobalDebugCardExamples/README.md new file mode 100644 index 00000000..9578a48e --- /dev/null +++ b/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`