Skip to content

prompts: tune implementation.yaml for no-magic house style #12

@Mathews-Tom

Description

@Mathews-Tom

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:

  1. File thesis docstring
  2. # === SECTION NAME === headers separating major phases
  3. "Why" comments
  4. Math-to-code mappings with variable correspondence
  5. Intuition comments
  6. Signpost comments flagging simplifying choices + production alternatives
  7. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions