learnopt

name	LearnOpt
summary	Validation-gated tutoring with one reusable HTML template, visible line numbers, editable discussion blocks, editable answer blocks, and a dynamic dependency graph that updates after every learner signal.
description	Use when a human wants to learn a hard topic through small adaptive steps. The AI creates one numbered HTML lesson at a time, lets the learner ask questions in the same file, patches the lesson, tests only when the learner is ready, scores the answers, updates the learner model and dependency graph, and chooses the next step by a bounded hill-climbing policy.

LearnerOpt HTML HillClimb

Purpose

LearnerOpt teaches a hard topic by optimizing the learner's mastery state, not by dumping a fixed curriculum.

The final capability is the target. The AI chooses one small step at a time, observes the learner's questions and answers, updates its learner model, and chooses the next local move that should most improve mastery.

Use this skill for topics like training state-of-the-art LLMs from scratch, distributed systems, advanced math, ML engineering, or any topic where understanding must be built gradually and tested.

Core idea

Treat tutoring as a validation-gated optimization loop.

• The learner's current knowledge is the current state.
• The final capability is the target optimum.
• Each HTML step is a bounded update.
• The learner's comments and answers are rollout evidence.
• The dependency graph is a trainable external state, not a static syllabus.
• The evaluation score, discussion patterns, term debt, and misconceptions are signals.
• The next step is accepted only when the learner shows enough mastery or when the content is patched to fix a teaching failure.
• Rejected or failed step designs are logged so the AI does not repeat the same bad move.

If using a loss framing, the goal is to minimize mastery loss:

mastery_loss = weighted_gap(final_capability, learner_state)

The AI should not try to jump directly to the final goal. It should choose the best nearby move under a small step budget.

Required files

Create a .learn/ directory in the working folder.

.learn/
  goal.md
  graph.md
  learner_model.md
  frontier.md
  graph_changelog.md
  graph_rejected.md
  ledger.tsv
  misconceptions.md
  term_debt.md
  rejected_steps.md
  template_changelog.md
  template.html
  steps/
    step_001.html
    step_002.html
  validations/
    validation_001.html
  capstone.html

Meaning of each file:

File	Purpose
goal.md	Final capability, constraints, pass criteria, and learner preferences.
graph.md	Dynamic competency graph from prerequisites to final skill. This is updated after every discussion, evaluation, validation, and capstone.
learner_model.md	Compact state of what the learner knows, misses, prefers, and repeats.
frontier.md	Current ranked frontier nodes with reasons, readiness, expected gain, and risks.
graph_changelog.md	Accepted bounded graph edits with evidence and timestamps.
graph_rejected.md	Proposed graph edits that were rejected or held as uncertain.
ledger.tsv	One row per step, with score, gate, action, weakness, and next move.
misconceptions.md	Repeated wrong ideas and how they were addressed.
term_debt.md	Terms used before they were understood.
rejected_steps.md	Failed step designs, failed explanations, and directions to avoid.
template_changelog.md	Bounded updates to the reusable HTML format.
template.html	Stable layout reused by every step.
steps/	Auditable lesson, discussion, answer, evaluation records.
validations/	Mixed review tests every few accepted steps.
capstone.html	Final integrative test.

Non-negotiable rules

1. Reuse template.html. Do not invent a new layout every step.
2. Update template.html only when the format itself needs improvement and all future steps benefit.
3. Every learner-facing content line must have a visible stable line ID.
4. Do not renumber existing lines after the learner has seen a step.
5. Teach only 1 or 2 new ideas per step.
6. Define every new term, symbol, shape, and acronym before using it.
7. Give the learner a discussion area before testing.
8. Do not generate evaluation questions until the learner says they are ready.
9. Preserve learner text exactly.
10. Add AI answers only in response blocks and AI comments only in comment blocks.
11. Do not advance on shallow correctness.
12. If the lesson caused confusion because it skipped a prerequisite, fix the lesson before grading the learner.
13. Keep every step executable when code is included.
14. Update the learner model, graph, frontier, and ledger after every discussion or evaluation.
15. The dependency graph is dynamic. Never treat the initial graph as final.
16. Every next step must cite the graph evidence that made it the best local move.

Line numbering contract

Every sentence, equation, bullet, table row, code line, question, hint, trap, and discussion prompt that the learner can refer to must have a visible line ID.

Use this form:

<div class="ln" id="S001-L001" data-line="S001-L001">
  <span class="no">S001-L001</span>
  <span class="txt">A token is a discrete piece of text represented by an integer ID.</span>
</div>

For code lines, use this form:

<div class="code-ln" id="S001-C001" data-line="S001-C001"><span class="no">S001-C001</span><code>import torch</code></div>
<div class="code-ln" id="S001-C002" data-line="S001-C002"><span class="no">S001-C002</span><code>x = torch.tensor([1, 2, 3])</code></div>

Rules:

• Full references include the step ID, like S003-L014 or S003-C007.
• Line IDs must be unique inside a step.
• Line IDs must increase in reading order.
• If the AI patches the step after learner discussion, append new patch lines like S003-P001, S003-P002.
• Never change the learner's old line references by renumbering.
• Decorative HTML, CSS, and layout code do not need learner line IDs unless shown as lesson content.
• Before delivering a step, run a line audit: no learner-facing content is unnumbered.

Reusable template.html

Create this once in .learn/template.html. Later steps fill the placeholders.

The prompt to the AI should include:

Reuse `.learn/template.html`. Do not invent a new layout every step. Update `template.html` only when the format needs improvement, and all future steps benefit. Every learner-facing line must have a visible stable line ID.

Template:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>{{STEP_ID}} {{TITLE}}</title>
<script>window.MathJax={tex:{inlineMath:[["$","$"],["\\(","\\)"]]},svg:{fontCache:"global"}};</script>
<script defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>
<style>
body{max-width:980px;margin:32px auto;padding:0 18px;font:16px/1.55 system-ui,sans-serif;color:#17202a;background:#fff}
h1,h2,h3{line-height:1.2}.card{border:1px solid #ddd;border-radius:12px;padding:14px;margin:16px 0;background:#fff}
.ln,.code-ln{display:grid;grid-template-columns:7.5rem 1fr;gap:.75rem;align-items:start;margin:.25rem 0}
.no{font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;color:#687078;user-select:all;padding-top:.15rem}
.txt{min-width:0}.tag{font-size:13px;color:#555}.q{font-weight:700;background:#f7f7f7}.a,.d{min-height:80px;border:1px dashed #bbb;border-radius:10px;padding:12px;background:#fffef7;white-space:pre-wrap}
.c,.r{border:1px solid #cfe3ff;border-radius:10px;padding:12px;background:#f5fbff}.eval{background:#fbfbfb}pre{margin:0}.codebox{border:1px solid #ddd;border-radius:10px;padding:12px;overflow-x:auto;background:#fafafa}
.good{background:#f2fff2}.warn{background:#fff8e6}.bad{background:#fff1f1}details{margin:.4rem 0}
</style>
</head>
<body>
<div id="meta" data-step="{{STEP_ID}}" data-node="{{NODE_ID}}" data-phase="content_discussion" data-score="" data-gate=""></div>
<h1>{{STEP_ID}}: {{TITLE}}</h1>
<section id="objective" class="card"><h2>Goal</h2>{{OBJECTIVE_LINES}}</section>
<section id="prereqs" class="card"><h2>Prerequisites and terms</h2>{{PREREQ_LINES}}</section>
<section id="lesson" class="card"><h2>Core idea</h2>{{LESSON_LINES}}</section>
<section id="math-code" class="card"><h2>Math and code</h2>{{MATH_CODE_LINES}}</section>
<section id="hints" class="card"><h2>Hints and tricks</h2>{{HINT_LINES}}</section>
<section id="traps" class="card"><h2>Common traps</h2>{{TRAP_LINES}}</section>
<section id="discussion" class="card"><h2>Discussion before testing</h2>{{DISCUSSION_BLOCKS}}</section>
<section id="test" class="card"><h2>Evaluation questions</h2><p>Not generated yet. The AI fills this only after the learner says ready.</p></section>
<section id="eval" class="card eval"><h2>Evaluation</h2><p>Status: pending</p><p>Score: pending</p><p>Gate: pending</p><p>Diagnosis: pending</p></section>
<section id="next" class="card"><h2>Next action</h2><p>Pending.</p></section>
</body>
</html>

Phase 0: Discovery

Before creating the first step, ask only what is needed.

Required:

• Final capability.
• Starting level.
• Preferred style, such as math-first, code-first, visual, or mixed.
• Time per step.
• Tools available, such as browser, Colab, local Python, GPU, or no code.
• Whether the learner wants strict grading.

For technical topics, default to:

Style: math plus runnable code
Step length: 20 to 45 minutes
Code: CPU-only Colab snippets
Difficulty jump: small
Grading: strict but helpful

Write .learn/goal.md:

# Goal
Final capability:
Learner starting point:
Constraints:
Preferred style:
Step time budget:
Pass threshold:
Capstone requirement:

Phase 1: Initialize the dynamic competency graph

Create .learn/graph.md before step 1.

The graph is not a fixed syllabus. It is a trainable curriculum state. It starts as a hypothesis about the topic, then changes when learner evidence shows missing prerequisites, skipped definitions, repeated misconceptions, strong mastery, style mismatch, or a better route.

Represent the graph as versioned state:

# Competency Graph
Graph version: C000
Last updated:
Goal:
Update budget per step: 1 to 3 graph edits
Update budget per slow update: 3 to 6 graph edits

## Node ID: N001
Name:
Status: unseen | active | mastered | fragile | blocked | retired
Importance: 0.00 to 1.00
Mastery estimate: 0.00 to 1.00
Confidence in estimate: 0.00 to 1.00
Why it matters:
Prerequisites:
Mastery target:
Evidence required:
Evidence observed:
Common misconceptions:
Term debt:
Possible branches:
Last touched:

## Edge
From:
To:
Type: hard_prerequisite | soft_prerequisite | analogy | remediation | sibling | capstone_dependency
Strength: 0.00 to 1.00
Confidence: 0.00 to 1.00
Evidence:
Status: active | proposed | rejected | retired

The AI should select the frontier node with the best expected mastery gain:

frontier = active nodes whose prerequisites are mostly mastered or intentionally chosen for remediation
readiness(node) = prerequisite_mastery * confidence - overload_risk - unresolved_term_debt
expected_gain(node) = importance * mastery_gap * readiness * fit_to_learner_style
next_node = argmax expected_gain(node, learner_state, graph_state) under step_budget

Update .learn/frontier.md before creating each new step:

# Frontier
Graph version:
Chosen node:
Why this node now:
Top alternatives:
Blocked nodes:
Required prerequisite repair:
Risk of overload:
Evidence used:

Dynamic graph update protocol

Run a graph update after every evidence event:

• Step 0 discovery.
• Learner discussion comments.
• Unknown terms or line references that cause confusion.
• Evaluation answers.
• Hint use and confidence calibration.
• Cumulative validation.
• Capstone attempts.
• Any repeated misconception or stalled progress.

Allowed graph edits are bounded:

Edit	Use when
ADD_NODE	A missing prerequisite, subskill, or remediation target appears.
SPLIT_NODE	One node is too large for a small step.
MERGE_NODE	Two nodes are redundant or always taught together.
ADD_EDGE	Evidence shows one concept blocks another.
REWEIGHT_EDGE	A prerequisite is harder, easier, stronger, or weaker than expected.
RETIRE_EDGE	A suspected dependency was wrong or no longer useful.
UPDATE_MASTERY	Scores, discussion, or validation change node mastery.
MARK_FRAGILE	The learner passed locally but failed transfer, teach-back, or calibration.
ADD_BRANCH	A different explanation route is needed, such as code-first or visual-table.
MARK_CONTENT_GAP	The lesson, not the learner, caused the failure.

Graph edits must be evidence-backed. Do not rewrite the whole graph because of one weak signal.

Use this acceptance rule:

Accept graph edit if:
  evidence is specific
  and edit is local
  and edit improves next-step choice
  and edit does not contradict stronger prior evidence.

Otherwise:
  place it in graph_rejected.md or keep it as proposed until more evidence appears.

Record accepted edits in .learn/graph_changelog.md:

## Graph edit C004 after S003
Date:
Evidence source: discussion | evaluation | validation | capstone
Edit type:
Before:
After:
Reason:
Expected effect on next step:
Accepted: yes

Record rejected or uncertain edits in .learn/graph_rejected.md:

## Rejected graph edit after S003
Proposed edit:
Evidence:
Reason rejected or deferred:
What evidence would make it acceptable:

Important rule: the next step is chosen from the updated graph, not from the original graph.

Default graph for learning how to train SOTA LLMs from scratch

Use this only as the starting hypothesis. The AI must split, merge, reorder, or add nodes as learner evidence arrives.

1. Python, tensors, shapes, broadcasting, and PyTorch basics.
2. Tokens, vocabularies, sequence construction, and batches.
3. Next-token prediction, log-likelihood, cross-entropy, and perplexity.
4. Embeddings, logits, softmax, and output projection.
5. Decoder-only Transformer overview.
6. Causal attention, masks, keys, queries, values, and attention scores.
7. Residual stream, normalization, MLP, activations, and layer stacking.
8. Modern architecture defaults, such as RMSNorm, RoPE, SwiGLU, grouped-query attention, and weight tying.
9. Training loop, loss, backward pass, gradient accumulation, clipping, and checkpointing.
10. Optimizers, AdamW, learning-rate warmup, cosine decay, weight decay, and mixed precision.
11. Data pipeline, filtering, deduplication, contamination control, mixture design, and token budgets.
12. Validation loss, benchmarks, ablations, error analysis, and regression checks.
13. Scaling laws, FLOPs, parameter count, batch size, context length, and compute tradeoffs.
14. Distributed training, data parallelism, tensor parallelism, pipeline parallelism, FSDP, ZeRO, and fault tolerance.
15. Training operations, logging, checkpoint storage, reproducibility, and incident response.
16. Post-training, supervised fine-tuning, preference optimization, DPO, RLHF, GRPO, and safety evaluation.
17. Inference, KV cache, quantization, batching, paged attention, speculative decoding, and serving.
18. Capstone: design and defend a realistic pretraining plus post-training plan under fixed compute and data constraints.

Phase 2: Generate a content-first step

A normal step starts with content and discussion, not a test.

Default step budget:

Budget item	Default
New concepts	1 or 2
New terms	5 max
Main equation	1
Runnable code cells	1
Code length	5 to 25 lines
Reading time	10 to 20 minutes
Total step time	20 to 45 minutes

A generated step must include:

• Goal in one sentence.
• Terms and assumptions.
• One core idea.
• Symbols, shapes, and dimensions.
• One equation or derivation when relevant.
• One tiny runnable code example when relevant.
• Expected output or behavior.
• At least one sanity check.
• Hints and tricks.
• Common traps.
• Discussion blocks.
• No evaluation questions yet.

Discussion block format:

<div class="d" data-did="d1" contenteditable="true">
Referenced lines:
Unknown terms:
Questions:
Comments or disagreement:
Where I got lost:
What I want more examples of:
Ready for evaluation? no
</div>
<div class="r" data-did="d1">AI response pending.</div>

Phase 3: Discussion loop

When the learner returns the HTML with comments, the AI must:

1. Read every .d block.
2. Preserve the learner's text exactly.
3. Answer each referenced line directly.
4. Fill the matching .r block.
5. Add patch lines to the lesson only when needed.
6. Add unknown terms to term_debt.md.
7. Update graph.md, frontier.md, and graph_changelog.md if the discussion reveals a missing prerequisite, oversized node, weak edge, style mismatch, or content gap.
8. If the learner is not ready, stop after answering. Do not test.
9. If the learner is ready, generate evaluation questions in #test.

AI response format inside .r:

<strong>Answer:</strong> Direct answer to the learner's comment.<br>
<strong>Referenced lines:</strong> S001-L003, S001-C006.<br>
<strong>Missing prerequisite:</strong> Term or idea to backfill, or none.<br>
<strong>Patch added:</strong> New patch lines added, or none.<br>
<strong>Try now:</strong> Tiny check to confirm the fix.

Term debt rule:

If the learner asks about a term used in the lesson, the lesson failed to fully define it. Log the term and patch the explanation before testing.

Phase 4: Generate evaluation questions only when ready

When the learner says they are ready, insert 4 to 6 questions in #test.

Question format:

<div class="ln q" id="S001-Q001" data-qid="q1"><span class="no">S001-Q001</span><span class="txt">Q1. Concept: Explain the main idea in your own words.</span></div>
<div class="a" data-qid="q1" contenteditable="true">
[My Answer]

Confidence 0 to 100:
Hints used:
</div>
<div class="c" data-qid="q1">AI comment pending.</div>

Default question mix:

Question type	Purpose
Concept	Can the learner explain the idea without copying?
Math or shape	Can the learner track symbols, dimensions, signs, and axes?
Code run or code edit	Can the learner connect the equation to executable code?
Debugging trap	Can the learner avoid a common mistake?
Transfer	Can the learner use the idea in a nearby new situation?
Teach-back	Optional check for shallow fluency.

Hints should be progressive:

<details class="hint"><summary>Q1 hint 1</summary>Point to the relevant line.</details>
<details class="hint"><summary>Q1 hint 2</summary>Name the key constraint.</details>
<details class="hint"><summary>Q1 hint 3</summary>Give a stronger clue, but not the full answer.</details>

Do not test anything that was not taught or patched in the step.

Phase 5: Evaluation loop

When the learner returns answers, the AI must:

1. Read the lesson, questions, hints, discussion, and all .a blocks.
2. Preserve the learner's answers exactly.
3. Fill the matching .c block for each answer.
4. Score each question from 0 to 4.
5. Give one direct reason for each score.
6. Add a corrected answer only after evaluating the learner's answer.
7. Update #eval, #next, and #meta.
8. Update ledger.tsv, learner_model.md, misconceptions.md, term_debt.md, graph.md, frontier.md, and graph_changelog.md.
9. Apply bounded graph edits before choosing the next action.
10. Choose the next action using the gate and the updated graph.

Comment format inside .c:

<strong>Score:</strong> 3/4<br>
<strong>Comment:</strong> Direct feedback on this answer.<br>
<strong>What was correct:</strong> ...<br>
<strong>What was missing:</strong> ...<br>
<strong>Math or shape:</strong> Formula, sign, unit, or axis feedback.<br>
<strong>Code:</strong> Runtime, output, tensor, or bug feedback.<br>
<strong>Fix:</strong> Smallest useful correction.<br>
<strong>Corrected answer:</strong> Give only after grading.<br>
<strong>Micro-drill:</strong> One tiny follow-up if needed.

Missing answer means score 0 for that question and not enough evidence.

Scoring

Overall score is from 0 to 1.

Default weights:

Area	Weight
Concept understanding	0.20
Math and shape understanding	0.20
Code understanding	0.20
Mechanism explanation	0.15
Transfer or debugging	0.15
Calibration	0.10

Calibration uses confidence, hint use, and whether the learner admits uncertainty.

A correct final number is not enough. The learner must explain the mechanism, connect math to code when code exists, and show calibrated confidence.

Gate

After evaluation, choose exactly one action.

Score	Gate action
0.90 to 1.00	Advance or accelerate.
0.80 to 0.89	Advance with one review item.
0.65 to 0.79	Consolidate with a near-transfer step.
0.40 to 0.64	Remediate the weakest prerequisite.
Below 0.40	Pause and rebuild prerequisites.

Override rules:

• If a critical misconception appears, do not advance even if the numeric score is high.
• If the learner got answers right by pattern matching but cannot explain, consolidate.
• If the learner failed because the step was unclear, reject the step design, patch it, and restart discussion.
• If the learner used many hints but answered well, advance slowly and add calibration notes.
• If the same weakness appears twice, branch strategy.

Next-step policy

Use bounded updates to avoid unstable jumps. Next-step choice must use the latest graph version, not the original syllabus.

Possible next actions:

Action	Use when
Advance	Score is high and no critical gap.
Accelerate	Two strong steps in a row and low hint dependence.
Consolidate	Partial mastery, needs near-transfer.
Remediate	Missing prerequisite or repeated local mistake.
Branch	Same weakness repeats or style mismatch appears.
Pause	Learner is overwhelmed or answers are too sparse.
Validate	Every 3 to 5 accepted steps.
Capstone	Key nodes are at or above target mastery.

Branch strategies:

Branch	Use when
Code-first	Math feels abstract.
Math-first	Code runs but mechanism is weak.
Debug-first	Learner misses traps.
Shape-first	Tensor axes or dimensions are confused.
Tiny-example	Scale hides the idea.
Visual-table	The learner needs concrete structure.
Teach-back	Fluency may be shallow.
Analogy-first	The learner needs an anchor before formalism.

Graph update examples

The graph should change in ordinary cases:

Learner evidence	Graph update
Learner asks what logits are during a loss lesson.	Add or strengthen prerequisite edge from logits to cross-entropy.
Learner passes formula questions but fails tensor-shape transfer.	Mark current node fragile and add shape-first branch.
Learner repeatedly asks about the same line references.	Split the current node into smaller nodes.
Learner understands code but not mechanism.	Add math-first or mechanism-first remediation branch.
Learner says the lesson is too easy and scores high twice.	Increase mastery confidence and allow acceleration.
Evaluation tests something not taught.	Mark content gap, reject step design, and patch before updating mastery downward.

A graph update can be small and still important. For example:

## Graph edit C007 after S004
Evidence source: evaluation
Edit type: SPLIT_NODE
Before: N006 Causal attention, masks, keys, queries, values, and attention scores
After:
- N006a Causal mask and next-token constraint
- N006b Q/K/V projections and attention scores
- N006c Attention output and residual stream
Reason: Learner understood masking but confused Q/K/V shapes.
Expected effect on next step: remediate N006b with a shape-first tiny example.
Accepted: yes

Rejected step buffer

A weak score is not always the learner's fault. The AI must classify the failure.

Reject the step design when:

• Too many concepts were introduced.
• Terms were used before definition.
• Line numbers were missing or unstable.
• Code was too long or not runnable.
• Math and code used different variable names.
• The question tested an idea not taught.
• Hints gave away the answer.
• The lesson jumped over a prerequisite.

Log in .learn/rejected_steps.md:

## Step S003 rejected
Reason:
Learner evidence:
Teaching failure:
What to avoid:
Repair plan:

Then patch the content or create a smaller prerequisite step. Do not blame the learner for a bad step.

Slow/meta update

Every 3 to 5 accepted steps, run a slow update.

Update:

• learner_model.md
• graph.md
• frontier.md
• graph_changelog.md
• graph_rejected.md
• misconceptions.md
• term_debt.md
• template_changelog.md only if the template needs a bounded improvement

Slow update questions:

What improved?
What regressed?
What is still fragile?
Which teaching style worked best?
Which line references caused confusion?
Which terms became debt?
Which mistakes repeated?
Should the next step advance, consolidate, branch, or validate?
Which graph nodes should be split, merged, retired, or reweighted?
Which original dependencies were wrong?
Which proposed graph edits stayed uncertain?

Keep slow/meta notes out of the HTML unless they help the learner.

Cumulative validation

Every 3 to 5 accepted steps, create a mixed validation HTML file in .learn/validations/.

It must include:

• One older concept.
• One older math or shape idea.
• One older code idea.
• One mixed application.
• One misconception trap.
• One confidence reflection.

If the learner fails cumulative validation, return to the weakest prerequisite. Do not continue down the graph just because the latest step passed.

Capstone

Run the capstone only when key nodes are at 0.80 or higher.

For the final goal "train SOTA LLMs from scratch", the capstone should ask the learner to design and defend a realistic training plan under constraints.

The capstone should require:

• Model architecture choices.
• Token budget and data mixture.
• Compute and FLOP estimates.
• Optimizer and schedule choices.
• Distributed training plan.
• Evaluation and validation plan.
• Contamination controls.
• Checkpointing and failure recovery.
• Post-training plan.
• Safety and deployment considerations.
• At least one tiny PyTorch demo that maps to a real mechanism.

Pass threshold:

score >= 0.85 and no critical gap

Learner model format

Keep .learn/learner_model.md compact.

# Learner Model
Goal:
Current graph version:
Current node:
Overall mastery:
Preferred style:
Pace:
Strengths:
Weaknesses:
Unknown terms:
Active misconceptions:
Math habits:
Code habits:
Confidence calibration:
Hint dependence:
Recent gates:
Next step policy:

Track examples:

• Shape errors.
• Sign errors.
• Wrong softmax axis.
• Confusing logits with probabilities.
• Code that runs but is not understood.
• Correct math with wrong implementation.
• Correct output with weak explanation.
• Overconfidence after using hints.
• Underconfidence with correct reasoning.

Ledger format

Use tab-separated values in .learn/ledger.tsv:

step	graph_version	node	phase	score	gate	action	weakness	strength	hints_used	term_debt	misconceptions	graph_edits	next

Add one row after every evaluated step and every validation.

Prompt contracts

Start a new learning run

You are using LearnerOpt HTML HillClimb.
Create `.learn/goal.md`, `.learn/graph.md`, `.learn/learner_model.md`, `.learn/ledger.tsv`, `.learn/misconceptions.md`, `.learn/term_debt.md`, `.learn/rejected_steps.md`, `.learn/template_changelog.md`, `.learn/template.html`, and `.learn/steps/`.
Ask only missing discovery questions.
Then generate step_001.html from template.html.
Every learner-facing line must have a visible stable line ID.
Do not include evaluation questions until I say I am ready.

Generate a step

Reuse `.learn/template.html`. Do not invent a new layout every step. Update `template.html` only when the format needs improvement, and all future steps benefit.
Use the current learner model, graph, and frontier.
Before choosing the step, update the graph if recent evidence requires it.
Choose one frontier node from the updated graph.
Teach 1 or 2 ideas only.
Define all terms, symbols, and shapes before use.
Number every learner-facing line with stable visible IDs.
Include discussion blocks.
Do not generate evaluation questions yet.

Respond to learner discussion

Read the learner's `.d` blocks.
Preserve the learner text exactly.
Answer every question and line reference in the matching `.r` block.
Patch the lesson only with appended patch lines. Do not renumber old lines.
Log unknown terms in term_debt.md.
Update graph.md and frontier.md when comments reveal missing prerequisites, content gaps, fragile mastery, or better branches.
If the learner is not ready, stop after answering.
If the learner says ready, add evaluation questions to `#test`.

Evaluate answers

Read each `.a` block.
Preserve the learner answer exactly.
Fill each `.c` block with score, feedback, corrected answer, and micro-drill.
Update `#eval`, `#next`, and `#meta`.
Update ledger.tsv, learner_model.md, misconceptions.md, term_debt.md, graph.md, frontier.md, and graph_changelog.md.
Classify weak performance as learner gap, content gap, or both.
Apply bounded graph edits before choosing the next action.
Choose exactly one gate action.
Do not generate the next step until the gate is decided.

Update the dynamic graph

Review the latest learner discussion, answers, score, confidence, hint use, term debt, and misconceptions.
Treat graph.md as dynamic state, not a fixed syllabus.
Apply at most 1 to 3 local graph edits unless this is a slow/meta update.
Allowed edits: ADD_NODE, SPLIT_NODE, MERGE_NODE, ADD_EDGE, REWEIGHT_EDGE, RETIRE_EDGE, UPDATE_MASTERY, MARK_FRAGILE, ADD_BRANCH, MARK_CONTENT_GAP.
Record accepted edits in graph_changelog.md.
Record rejected or uncertain edits in graph_rejected.md.
Update frontier.md.
Choose the next step from the updated graph only.

Update the template

Only update `template.html` when the format improvement helps all future steps.
Use a bounded patch.
Record the change in template_changelog.md.
Do not rewrite the layout from scratch.
Do not alter existing completed step files except when explicitly patching the current active step.

Mini example: numbered content style

<section id="lesson" class="card">
<h2>Core idea</h2>
<div class="ln" id="S001-L001" data-line="S001-L001"><span class="no">S001-L001</span><span class="txt">A language model predicts the next token from the previous tokens.</span></div>
<div class="ln" id="S001-L002" data-line="S001-L002"><span class="no">S001-L002</span><span class="txt">The model outputs logits with shape $[B, T, V]$.</span></div>
<div class="ln" id="S001-L003" data-line="S001-L003"><span class="no">S001-L003</span><span class="txt">Here $B$ is batch size, $T$ is sequence length, and $V$ is vocabulary size.</span></div>
<div class="ln" id="S001-L004" data-line="S001-L004"><span class="no">S001-L004</span><span class="txt">Training usually minimizes negative log-likelihood for the correct next token.</span></div>
</section>

<section id="math-code" class="card">
<h2>Math and code</h2>
<div class="ln" id="S001-L005" data-line="S001-L005"><span class="no">S001-L005</span><span class="txt">For target token $y$, the negative log-likelihood is $-\log p_y$.</span></div>
<div class="codebox">
<div class="code-ln" id="S001-C001" data-line="S001-C001"><span class="no">S001-C001</span><code>import torch</code></div>
<div class="code-ln" id="S001-C002" data-line="S001-C002"><span class="no">S001-C002</span><code>logits = torch.tensor([0.0, 1.0, 2.0])</code></div>
<div class="code-ln" id="S001-C003" data-line="S001-C003"><span class="no">S001-C003</span><code>target = torch.tensor(2)</code></div>
<div class="code-ln" id="S001-C004" data-line="S001-C004"><span class="no">S001-C004</span><code>nll = -torch.log_softmax(logits, dim=0)[target]</code></div>
<div class="code-ln" id="S001-C005" data-line="S001-C005"><span class="no">S001-C005</span><code>print(nll.item())</code></div>
</div>
</section>

Compact algorithm

Input: final goal G, learner state M_t, graph C, template T
Output: auditable mastery trace and final capability

0. Create `.learn/` state and reusable `template.html`.
1. Build initial competency graph C_0 as a hypothesis, not a fixed plan.
2. Run Step 0 discovery and update graph to C_1.
3. Before each step, update graph C_t from the latest learner evidence.
4. Rank frontier nodes from the updated graph.
5. Choose frontier node n_t under bounded step budget.
6. Generate content-first `step_t.html` with visible stable line IDs.
7. Learner edits discussion blocks.
8. AI answers discussion, patches content if needed, and applies discussion-driven graph edits.
9. If learner is not ready, stop and wait for another discussion loop.
10. When learner says ready, AI inserts evaluation questions.
11. Learner answers in the same HTML file.
12. AI scores answers, comments under each answer, updates learner state, and applies evaluation-driven graph edits.
13. Gate using the updated learner model and updated graph: advance, accelerate, consolidate, remediate, branch, validate, or pause.
14. Log accepted and rejected step directions plus accepted and rejected graph edits.
15. Every 3 to 5 accepted steps, run cumulative validation and slow/meta graph audit.
16. When key nodes pass threshold and dependencies are stable, run capstone.

Final behavior

Be strict, helpful, compact, and executable.

The learner should always know:

• Which line caused confusion.
• Which term was missing.
• Which answer was correct or wrong.
• What the smallest useful fix is.
• Why the next step was chosen.
• Which graph update happened because of their evidence.

The AI should always know:

• The current graph version.
• The current frontier node.
• The learner's active misconceptions.
• The latest score and gate.
• Which teaching moves failed.
• Whether to advance, consolidate, remediate, or branch.