charleshoskinson/sevenlayer/plans

.claude/skills/math-explainer/
  SKILL.md                       # frontmatter + six-stage orchestration (Task 1 skeleton, Task 8 body)
  conftest.py                    # puts the skill dir on sys.path for tests (Task 1)
  references/
    sanderson-moves.md           # Method Engine card — 10 moves (Task 2)
    tao-staging.md               # Method Engine card — 3 phases + 2 maxims (Task 2)
    dependency-protocol.md       # Stage 1 protocol (Task 7)
    accuracy-protocol.md         # Stage 4 protocol (Task 7)
    pipeline.md                  # six stages in operational detail (Task 7)
  scripts/
    __init__.py                  # makes scripts importable (Task 1)
    scorecard.py                 # Stage 6 gate (Task 3)
    resolve_deps.py              # Stage 1 resolver (Task 4)
    run_sage.py                  # Stage 3/4 Sage runner (Task 5)
    recipes/schwartz_zippel.sage # sample correct-by-construction figure (Task 5)
    manim_render.py              # Stage 3 manim value validator (Task 6)
    check_env.py                 # dependency doctor (Task 10)
  evals/
    concepts.json                # eval concept list (Task 9)
    run_eval.py                  # headless eval harness (Task 9)
    sample_bundle/bundle.json    # a complete Stage-6 bundle for scorecard eval (Task 9)
  tests/
    test_structure.py            # skill layout + content lints (Tasks 1,2,7,8)
    test_scorecard.py            # Task 3
    test_resolve_deps.py         # Task 4
    test_run_sage.py             # Task 5
    test_manim_render.py         # Task 6
    fixtures/mini_foundations.md # resolver fixture (Task 4)

{
  "concept": "Schwartz–Zippel lemma",
  "phases": {"pre_rigorous": "…", "rigorous": "…", "post_rigorous": "…"},
  "modes_order": ["analogy", "visual", "worked_example", "formal", "synthesis"],
  "led_with_visual": true,
  "motivated_before_defined": true,
  "notation_in_pre_rigorous": false,
  "heuristic_rigorous_pairs": [["random spot-check picture", "P(agreement) ≤ d/|F|"]],
  "stuck_points_predicted": ["thinks completeness needs a large field"],
  "stuck_points_addressed": ["thinks completeness needs a large field"],
  "accuracy_verified": true,
  "comprehension_levels": ["recall", "apply", "transfer", "rediscover"],
  "rediscovery_prompt_present": true
}

from pathlib import Path
SKILL = Path(__file__).resolve().parents[1]
def test_skill_md_has_frontmatter():
    text = (SKILL / "SKILL.md").read_text(encoding="utf-8")
    assert text.startswith("---"), "SKILL.md must start with YAML frontmatter"
    fm = text.split("---", 2)[1]
    assert "name: math-explainer" in fm
    assert "description:" in fm
def test_layout_dirs_exist():
    for d in ("references", "scripts", "tests"):
        assert (SKILL / d).is_dir(), f"missing dir: {d}"

---
name: math-explainer
description: Use when drafting a mathematical concept explanation for the "Proving Nothing" book — produces book-ready, dependency-aware, multimodal (Sage + manim), fact-checked material executing the Sanderson + Tao teaching method via a six-stage pipeline. Triggers include "explain <concept>", "draft the math for <concept>", "build the explanation for <concept>". Not for systems/applications prose, source ingestion, or interactive tutoring.
---
 
# math-explainer
 
Six-stage pipeline (full body added in Task 8). Reference cards in `references/`; helper scripts in `scripts/`.

import os, sys
sys.path.insert(0, os.path.dirname(__file__))

git add .claude/skills/math-explainer
git commit -m "feat(math-explainer): scaffold skill dir, SKILL.md skeleton, structure test"

def test_method_cards_exist_and_have_content():
    s = (SKILL / "references" / "sanderson-moves.md").read_text(encoding="utf-8")
    # ten numbered moves
    for n in range(1, 11):
        assert f"{n}." in s, f"sanderson-moves.md missing move {n}"
    t = (SKILL / "references" / "tao-staging.md").read_text(encoding="utf-8")
    for phase in ("pre-rigorous", "rigorous", "post-rigorous"):
        assert phase in t.lower(), f"tao-staging.md missing phase: {phase}"
    assert "destroy bad intuition" in t.lower()

# Sanderson moves — how to build the intuition
 
Apply these in the pre-rigorous and post-rigorous phases. The binding constraint is motivation, not polish.
 
1.**Lead with the visual.** Show before you tell; ownership comes from seeing first.
2.**Concrete before abstract.** A specific example precedes any general framework.
3.**Empower the learner.** Frame so the reader feels they could have discovered it.
4.**Motivate before defining.** Establish the "why" before notation or formal definition.
5.**Anchor on one key example.** A single meaningful case (use the running Sudoku when it fits).
6.**Tell a story.** Tension → mystery → resolution.
7.**Minimize notation early.** Introduce symbols only when earned.
8.**Exploit symmetry/structure.** Make the result feel inevitable.
9.**Leave room for the "aha".** Don't over-explain; preserve the realization.
10.**Invite active rediscovery.** "You could have invented this" — the reader derives, not receives.
 
Sources: Sanderson via the Buteau distillation; Dwarkesh & Stanford Daily interviews.

# Tao staging — how to stage the rigor
 
Stage every explanation in three phases.
 
-**Pre-rigorous** — intuition, examples, computation. Sanderson moves dominate.
-**Rigorous** — precise definitions, theorems, proof sketch; notation is now *earned*.
-**Post-rigorous** — intuition rebuilt on rigor; use "both halves at once".
 
**Maxim 1.** The point of rigour is not to destroy all intuition; it should **destroy bad intuition** while clarifying and elevating good intuition. (Use the rigorous phase to kill the Stage-2 bad intuitions explicitly.)
 
**Maxim 2 (goal state).** Every heuristic argument naturally suggests its rigorous counterpart, and vice versa — so **pair every picture with its formal statement** in the post-rigorous phase.
 
**On-ramp tactics.** Ask "dumb questions" and answer them rigorously; anthropomorphize the objects; target the sub-step just beyond reach.
 
Source: Tao, "There's more to mathematics than rigour and proofs"; Tao MasterClass.

git add .claude/skills/math-explainer/references .claude/skills/math-explainer/tests/test_structure.py
git commit -m "feat(math-explainer): add Sanderson and Tao method cards + lint"

import json
from scripts.scorecard import evaluate
def complete_bundle():
    return {
        "concept": "Schwartz–Zippel lemma",
        "phases": {"pre_rigorous": "a", "rigorous": "b", "post_rigorous": "c"},
        "modes_order": ["analogy", "visual", "worked_example", "formal", "synthesis"],
        "led_with_visual": True,
        "motivated_before_defined": True,
        "notation_in_pre_rigorous": False,
        "heuristic_rigorous_pairs": [["picture", "P ≤ d/|F|"]],
        "stuck_points_predicted": ["big-field misconception"],
        "stuck_points_addressed": ["big-field misconception"],
        "accuracy_verified": True,
        "comprehension_levels": ["recall", "apply", "transfer", "rediscover"],
        "rediscovery_prompt_present": True,
    }
def test_complete_bundle_passes_all_checks():
    checks = evaluate(complete_bundle())
    assert all(c["ok"] for c in checks), [c for c in checks if not c["ok"]]
def test_missing_visual_fails_that_check():
    b = complete_bundle()
    b["led_with_visual"] = False
    checks = {c["id"]: c["ok"] for c in evaluate(b)}
    assert checks["led_with_visual"] is False