ADR-010: Explained prerequisite planning and evidence-based mastery

Status: accepted · Date: 2026-09-10

Context

The goal is ad-lateral-movement; recommendations must respect prerequisites and limited daily time. Reading alone does not prove procedural or explanatory skill.

Decision

Compute prerequisite closure, reject cycles, topologically order eligible concepts (mastery < 0.8, not deprecated), then rank with goal relevance 40%, importance 25%, mastery gap 20%, foundational centrality 15%. Break ties by difficulty and stable ID. Allocate 20 minutes reviews, 15 study, 40 lab, 15 writeup/teach-back.

Track recall, lab execution, and explanation separately. Anki owns scheduling; Deadwire owns path selection and exports stable IDs. Every recommendation explains prerequisites, evidence, score components, and estimated time.

For the first implementation, update each dimension with an exponentially weighted mean: new = 0.7 * old + 0.3 * bounded_event_score, where the event score is 0–1 and a missing dimension remains missing rather than becoming zero. Overall mastery is the minimum of the three observed dimensions once all exist; otherwise it is the mean of observed dimensions with an explicit cold_start flag. A lab score cannot be inferred from a recall score. Events are immutable, keyed by event_id, and evidence links are required for lab and explanation events.

Tests and consequences

Promotion correction, 2026-09-11

A partial mean describes observed scores only. It must never satisfy a prerequisite or remove a concept from the study queue. Promotion requires all three dimensions to exist and each to meet the threshold. Cold-start recommendations keep a full mastery-gap priority and explicitly list missing dimensions. Unapproved prerequisites remain blocking even if someone supplies scores for them. Ranking ties use difficulty followed by stable ID, rather than estimated lab duration.

The executable planner accepts an already scoped concept set with goal-relevance ratings. goal_id labels the returned explanation; automatic selection of a goal's concept closure remains work to implement. The current learning command still stores a score snapshot rather than a recoverable event history; do not treat that snapshot as proof of seven practice days.

Test cycles, missing references, deterministic ranking, carry-forward, duplicate learning events, and cold-start scores. Heuristics are transparent but not a validated psychometric model; revisit after observed learning data.

Alternatives considered

A purely linear reading order was rejected because prerequisite gaps make advanced labs misleading. Ranking by popularity or source frequency was rejected because repeated text is not evidence of importance. A single mastery score was rejected because recall, practical execution, and explanation fail independently. Anki scheduling was not reimplemented; Anki remains the card scheduler and Deadwire selects the next concept.

Implementation mechanics and example

For goal ad-lateral-movement, first compute the prerequisite closure and topologically order it. An eligible concept has all prerequisites at or above the configured threshold and is not deprecated. Score it as 0.40*goal_relevance + 0.25*importance + 0.20*mastery_gap + 0.15*foundational_centrality; break ties by difficulty and stable ID. The explanation includes prerequisites, each contribution, evidence, and estimated minutes, so a learner can challenge the recommendation.

Configuration and failure behavior

The default threshold is 0.8 and the daily plan is 20 minutes review, 15 study, 40 lab, and 15 write-up/teach-back. Long labs are split into bounded steps; incomplete work carries forward and never becomes complete automatically. A cycle, unresolved prerequisite, missing evidence, or deprecated goal blocks the path and creates an actionable review error. Cold-start dimensions remain missing; they are never coerced to zero.

Verification and revisit trigger

Tests cover cycle detection, unresolved references, deterministic tie-breaking, prerequisite closure, score bounds, carry-forward, duplicate event IDs, and cold-start behavior. A real learner outcome requires seven recorded practice days and a 30-day comparison; automated extraction metrics cannot claim it. Revisit weights only after a pre-registered analysis of observed learning data.

The offline Anki adapter is deliberately one-way: deadwire anki-export writes stable concept IDs, prompts, definitions, and tags, while review intervals remain in Anki. An optional AnkiConnect integration must preserve the same IDs and may not become the source of truth for prerequisites or mastery evidence.