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

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:

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:

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.

# 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