diff --git a/ProblemMap/Atlas/Fixes/templates/colab-template.md b/ProblemMap/Atlas/Fixes/templates/colab-template.md new file mode 100644 index 00000000..d2923318 --- /dev/null +++ b/ProblemMap/Atlas/Fixes/templates/colab-template.md @@ -0,0 +1,468 @@ + + +# Colab Template + +## Title + +Replace this line with a short clear title. + +Example: +`F4 Readiness Gate Demo - Minimal closure repair notebook` + +--- + +## 0. Quick summary + +Write 1 to 3 short sentences. + +Example: +This notebook demonstrates a workflow failure caused by missing readiness checks. +It compares the broken baseline with a repaired version that adds a simple readiness gate. + +--- + +## 1. Notebook type + +Choose one or more: + +- demo notebook +- benchmark rerun +- repair notebook +- trace notebook +- reproduction notebook +- comparison notebook + +--- + +## 2. Atlas routing context + +**Primary family** +`F?` + +**Secondary family** +`F?` or `None` + +**Broken invariant** +Write one short sentence. + +**Best current fit** +Write the nearest node, family entry, or edge-fit wording. + +**Why this notebook belongs here** +Write 2 to 4 short sentences. + +--- + +## 3. Problem this notebook addresses + +Describe the specific problem this notebook demonstrates. + +Useful questions: + +- what is broken in the baseline +- why a notebook is useful here +- what first repair move is being tested +- what this notebook is not trying to solve + +Keep this short and concrete. + +--- + +## 4. Intended use + +State clearly how this notebook should be used. + +Examples: + +- first public demo +- contributor reproduction +- benchmark sanity check +- teaching notebook +- route-first repair demonstration + +Optional format: + +**Use stage** +`...` + +**Target user** +`...` + +**Expected runtime** +`...` + +--- + +## 5. Required inputs + +List the minimum inputs. + +Examples: + +- corpus +- query set +- schema file +- workflow config +- notebook parameters +- baseline JSON +- expected JSON + +Use a short format like: + +```text +Input A: +Input B: +Input C: +```` + +--- + +## 6. Notebook sections + +A good notebook should usually contain these sections. + +### Section A · Setup + +What the notebook loads or installs. + +### Section B · Case framing + +What case is being shown and how it routes in the atlas. + +### Section C · Broken baseline + +Show the failure first. + +### Section D · First repair move + +Apply the family-level first repair move. + +### Section E · Re-run + +Run the repaired version. + +### Section F · Comparison + +Show before / after differences. + +### Section G · Optional WFGY escalation + +Show how the same case could be explored more deeply if needed. + +--- + +## 7. Baseline failure + +Describe the broken baseline. + +Useful questions: + +* what is the baseline workflow +* what fails first +* what visible symptom appears +* why is this failure interesting + +Optional mini format: + +**Baseline setup** +`...` + +**Broken behavior** +`...` + +**Failure note** +`...` + +--- + +## 8. First repair move + +Describe the first repair move being tested. + +Useful questions: + +* what intervention is being applied +* why it is the correct first move +* what should improve after the intervention + +Optional mini format: + +**Repair action** +`...` + +**Why this is first** +`...` + +**Expected improvement** +`...` + +--- + +## 9. Expected outputs + +Describe what the notebook should produce. + +Examples: + +* before / after metrics +* clearer trace output +* better schema pass rate +* fewer wrong anchors +* successful closure +* improved support rate + +Optional format: + +**Before** +`...` + +**After** +`...` + +**Success signal** +`...` + +--- + +## 10. Suggested evaluation fields + +List only useful fields. + +Examples: + +* `support_rate` +* `closure_success` +* `schema_pass_rate` +* `trace_completeness` +* `wrong_anchor_rate` +* `field_loss_count` + +Optional mini block: + +```text +Metric 1: +Metric 2: +Metric 3: +``` + +--- + +## 11. Misrepair warning + +This section is required. + +### Wrong first move + +`...` + +### Why it is tempting + +`...` + +### Why this notebook is not meant for that + +`...` + +This helps prevent notebooks from teaching the wrong reflex. + +--- + +## 12. Optional WFGY escalation + +Use this only if deeper WFGY exploration is relevant. + +### When to escalate + +`...` + +### What should be passed into WFGY + +* routed family +* broken invariant +* first repair already attempted +* unresolved pressure + +### What WFGY is expected to add + +`...` + +Do not use this section to skip atlas routing. + +--- + +## 13. Files included + +List the files included. + +Example: + +* `demo.ipynb` +* `input.json` +* `expected_output.json` +* `README.md` + +--- + +## 14. Runtime and dependency notes + +Be explicit. + +Examples: + +* Python version +* notebook runtime type +* external packages +* API keys if needed +* GPU not required +* internet required or not required + +Short, clear notes are enough. + +--- + +## 15. Limitations + +Be honest. + +Examples: + +* toy dataset only +* small case only +* one model family only +* partial demo, not full system benchmark +* notebook proves first move, not full closure + +--- + +## 16. One-line maintainer note + +Write one short line that helps review the contribution. + +Example: +Small F4 closure demo notebook with before / after run and simple success metric. + +--- + +## 17. Copy-paste mini skeleton + +Use this when you want the fastest possible start. + +```md +# Title + +## 0. Quick summary +... + +## 1. Notebook type +... + +## 2. Atlas routing context +Primary family: +Secondary family: +Broken invariant: +Best current fit: +Why this notebook belongs here: + +## 3. Problem this notebook addresses +... + +## 4. Intended use +Use stage: +Target user: +Expected runtime: + +## 5. Required inputs +... + +## 6. Notebook sections +A. +B. +C. +D. +E. +F. +G. + +## 7. Baseline failure +... + +## 8. First repair move +... + +## 9. Expected outputs +... + +## 10. Suggested evaluation fields +... + +## 11. Misrepair warning +Wrong first move: +Why it is tempting: +Why this notebook is not meant for that: + +## 12. Optional WFGY escalation +... + +## 13. Files included +... + +## 14. Runtime and dependency notes +... + +## 15. Limitations +... + +## 16. One-line maintainer note +... +``` + +--- + +## 18. Closing note + +A good notebook contribution does not need to be huge. + +It only needs to be: + +* routed +* runnable +* scoped +* inspectable +* honest about limits +