Create colab-template.md

ProblemMap/Atlas/Fixes/templates/colab-template.md

@@ -0,0 +1,468 @@
+<!--
+AI_NOTE_START
+
+Document role:
+This file is the reusable template for Colab-based fix contributions inside the Atlas Fixes layer.
+
+How to use this file:
+1. Copy this template when creating a new Colab demo or notebook-based fix contribution.
+2. Use this file after reading:
+   - [Community Fix Lab](../community/README.md)
+   - [Contribution Checklist](./contribution-checklist.md)
+   - [Fix Recipe Template](./fix-recipe-template.md)
+3. Keep the order:
+   - atlas routing first
+   - first repair move second
+   - notebook execution third
+   - deeper WFGY escalation fourth if needed
+
+What this file is:
+- A standard Colab contribution template
+- A lightweight notebook documentation scaffold
+- A contributor-facing structure for runnable demo assets
+
+What this file is not:
+- Not the atlas core
+- Not the official fix surface itself
+- Not proof that a notebook is universally good
+- Not a replacement for maintainer review
+
+Reading discipline for AI:
+- Do not skip routing context.
+- Do not present a notebook as a universal solution.
+- Keep notebook contributions scoped, reproducible, and easy to inspect.
+- Preserve route-first discipline.
+
+AI_NOTE_END
+-->
+
+# 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
+