Context
A 2026-04-19 smoke run (integration_test.py --tier 1 --limit 1 on insertion_sort, model openai/gpt-5.4) produced a clean classical-algorithm implementation but the output does not satisfy the no-magic repo's quality bar documented in no-magic/.claude/CLAUDE.md and no-magic/CONTRIBUTING.md.
Observed gaps in generated insertion_sort.py
| no-magic requirement |
Observed in output |
random.seed(42) as first executable line |
Missing |
| File thesis docstring (one-sentence "what this proves") |
Absent — generic API docstring instead |
Section headers # === SECTION NAME === |
Missing |
micro<name>.py naming convention |
Plain insertion_sort.py (packaging may rename) |
| Signpost comments on production alternatives |
Missing |
| Intuition / math-to-code comments |
Missing |
| Comment density 30-40% |
Below target |
Why this matters
Apprentice is intended to generate entries for the no-magic catalog, where the commenting standard IS the primary review criterion. Generic educational code is not mergeable into that catalog.
Proposed fix
Update src/apprentice/prompts/implementation.yaml (and likely instrumentation.yaml) to include the canonical 7-point commenting standard from no-magic/CONTRIBUTING.md:
- File thesis docstring
# === SECTION NAME === headers separating major phases
- "Why" comments
- Math-to-code mappings with variable correspondence
- Intuition comments
- Signpost comments flagging simplifying choices + production alternatives
- No obvious comments (every comment adds information the code doesn't convey)
Plus hard-requires: random.seed(42) first executable line, stdlib-only imports, micro<name>.py filename, 10-min runtime cap.
Verification
Re-run the smoke test after prompt update. Target artifact should pass no-magic/scripts/verify.py and visually match the style of no-magic/03-systems/microquant.py.
Context
A 2026-04-19 smoke run (
integration_test.py --tier 1 --limit 1oninsertion_sort, modelopenai/gpt-5.4) produced a clean classical-algorithm implementation but the output does not satisfy the no-magic repo's quality bar documented inno-magic/.claude/CLAUDE.mdandno-magic/CONTRIBUTING.md.Observed gaps in generated
insertion_sort.pyrandom.seed(42)as first executable line# === SECTION NAME ===micro<name>.pynaming conventioninsertion_sort.py(packaging may rename)Why this matters
Apprentice is intended to generate entries for the
no-magiccatalog, where the commenting standard IS the primary review criterion. Generic educational code is not mergeable into that catalog.Proposed fix
Update
src/apprentice/prompts/implementation.yaml(and likelyinstrumentation.yaml) to include the canonical 7-point commenting standard fromno-magic/CONTRIBUTING.md:# === SECTION NAME ===headers separating major phasesPlus hard-requires:
random.seed(42)first executable line, stdlib-only imports,micro<name>.pyfilename, 10-min runtime cap.Verification
Re-run the smoke test after prompt update. Target artifact should pass
no-magic/scripts/verify.pyand visually match the style ofno-magic/03-systems/microquant.py.