Graduated Implementation

Start with the smallest slice you can fully understand. Earn the

next notch by proving you understood the last one. Ambition that

outruns understanding is how a fluent diff becomes an unverifiable

one.

Graduated Implementation

Overview

The sibling skill imbue:assisted-mastery fades scaffolding as competence grows. This skill ramps the other axis: the ambition of the next increment. They are the two directions of one move, the graduated practice that turned novices into experts long before agents existed. Not "ban the tool," but "couple the next challenge to demonstrated competence on the last one."

The learning sciences give the move a number. Wilson et al. (2019, Nature Communications 10:4646) derive the optimal training point for a learner at roughly 85% success: hard enough to learn from, not so hard that the signal is noise. The same band is what Vygotsky's zone of proximal development, Ericsson's edge of ability, and Csikszentmihalyi's flow channel all gesture at. Bloom's mastery learning (advance a unit at >=90% on a fresh check), Bayesian Knowledge Tracing (advance at p(mastery) >= 0.95), and competence-based curriculum learning (Platanios et al. 2019, only attempt tasks within the current competence) are the same rule at different resolutions.

The danger this guards against is specific. An agent that one-shots a large change is maximally helpful to throughput and quietly corrosive to verification: you cannot review what you did not watch get built, and automation bias means you will trust it precisely when it is wrong (Perry et al. 2023). Aviation named the endpoint "children of the magenta": ramp the operator's autonomy faster than their retained understanding and they can no longer hand-fly or override the automation when it misbehaves.

The Three Practices

1. Start at the smallest intentional increment

Do not design the whole system up front. Pick the smallest slice that is a real, end-to-end step and stop there. The default rung is about 40 added lines: a change a human can read and explain in one sitting. The bound is the point, not a nuisance: it keeps understanding in pace with output. The guard_scope_ramp.py hook makes this concrete by flagging an increment that jumps past the current rung.

2. Ramp a notch only on demonstrated understanding

The next increment may be more ambitious only after the prior one's understanding is demonstrated and recorded. The check is sized to blast radius, the advancement gate:

• Low-stakes increment: ramp on an evidence gate. The prior

slice has green tests and a recorded tradeoff (what was chosen, what was rejected, why).

• High-stakes increment (auth, migrations, money, infra,

crypto): ramp only when the human explains the prior diff unaided. This is the magenta hand-fly check. If they cannot explain it, the rung drops rather than rises.

Recording the demonstration mints a ramp token (touch .imbue/ramp-ok), which the hook consumes to widen the rung one notch. You ramp by proving you understood the last slice, not by writing more. Each notch is appended to the ramp ledger so a reviewer can later audit that the demonstration was real, not rubber-stamped.

3. Hold the 85% band in both directions

Advancing too fast is one failure; never advancing is the other.

• Below the band (the human is lost, the slice was too big): hold,

shrink the increment, re-scaffold. Do not ramp.

• In the band (clean demonstration, some genuine effort): ramp one

notch.

• Above the band (the human clears it trivially, repeatedly): ramp

faster. Drilling a mastered skill is over-practice, the boredom failure that gets spaced-repetition decks abandoned (Cen & Koedinger 2007).

When to Use

• An agent is building a feature across more than one increment and

the human will maintain or be accountable for it.

• The work touches an unfamiliar subsystem or a high-stakes path.
• The human is building skill in an area, not just shipping a

throwaway.

Skip it for a single bounded edit, a trivial reversible change, or generated and vendored code. Forcing a ramp ritual on a typo fix is ceremony, and ceremony trains people to ignore the gate.

Red Flags

Related Skills

• imbue:assisted-mastery: fades scaffolding as competence grows;

this skill ramps challenge. Two directions, one axis.

• imbue:proof-of-work: the evidence half of the low-stakes gate.
• imbue:scope-guard: bounds the branch; this bounds the

increment within it.

• leyline:risk-classification: the stakes tier that selects which

gate (evidence vs explanation) applies.

• leyline:decision-journal: the durable home for the recorded

tradeoff that mints a ramp token.

The empirical basis for the 85% band, the failure modes, and the cross-domain gate design is preserved in research-basis.md.

Exit Criteria

• [ ] The first increment of the feature was bounded to roughly the

start rung, not the whole design.

• [ ] Each ramp to a more ambitious increment was preceded by a

recorded demonstration of the prior increment (a tradeoff entry; for high-stakes paths, the human explaining the diff unaided).

• [ ] The stakes tier was used to choose the evidence gate vs the

explanation gate, not defaulted silently.

• [ ] An increment that put the human below the understanding band

triggered a hold and a smaller next slice, not a ramp.

Advancement Gate

The gate decides whether the agent may ramp the next increment's ambition a notch. It is the load-bearing part of graduated implementation: too lax and ambition outruns understanding (blind trust); too strict and the work never advances (over-drilling). The design target is the ~85% band.

The gate by stakes

The stakes tier (from leyline:risk-classification) selects which check must pass before the rung widens.

The high-stakes gate uses an unrehearsed question about the actual change, not a recap the agent fed the human. This is the sight-reading principle from graded music exams and the reason medicine rejected "see one, do one, teach one": confidence outran competence when the test was a rehearsal. A signal that is cheap to fake (completion, a streak, a yes) will be faked; the gate has to cost what understanding costs.

The tier comes from leyline:risk-classification. The hook reads it from the IMBUE_STAKES environment variable or a one-line .imbue/stakes file (values GREEN, YELLOW, RED, CRITICAL); when neither is set it falls back to a path heuristic (a high-stakes path is treated as RED). The rung scales with the tier: GREEN and YELLOW keep the full rung, RED halves it, and CRITICAL quarters it, so the riskier the change the sooner a demonstration is forced.

Why the producer cannot self-certify

The agent that wrote the increment may not be the one that grades readiness to ramp. This is the four-eyes principle, and it is the universal anti-gaming device across every apprenticeship domain studied: the guild masterpiece judged by other masters, the visiting examiner, the medical milestone observed by a supervisor. A producer grading its own readiness is the automation-bias trap in miniature. See imbue:proof-of-work module independent-verification for the high-stakes verification rule this builds on.

The three failure modes the gate guards

1. Advancing too fast (under-mastery). A large increment passes because the signal was cheap. Guard: the rung only widens by one notch per recorded demonstration, and high-stakes paths get a halved rung so they force a demonstration sooner. 2. Never advancing (over-drill, boredom). The human clears every slice trivially but the rung never grows, or a single stumble ratchets it down and traps the work (the spaced- repetition "ease hell" that gets decks abandoned). Guard: ramp faster when the human is clearly above the band; never ratchet the rung down on one miss alone. 3. Gaming the metric (Goodhart). Optimizing the signal instead of the skill: padding tests, memorizing the recap, clicking through. Guard: the high-stakes check is a novel question, the producer is not the certifier, and the demonstration is recorded where it can be audited later.

How the hook operationalizes the gate

guard_scope_ramp.py (PreToolUse on Write, Edit, MultiEdit) holds each increment to the current rung:

• The rung starts bounded (RUNG_START, ~40 added lines) and

widens by RAMP_FACTOR per ramp token, capped at RUNG_CAP.

• A ramp token is IMBUE_RAMP_OK=1 or a .imbue/ramp-ok file,

created only after a demonstration is recorded and consumed on use, so one demonstration buys one notch.

• High-stakes paths (auth, migration, payment, infra, crypto) get a

halved effective rung.

• Shadow mode (default) warns; VOW_SHADOW_MODE=0 blocks an

over-rung increment. The hook never blocks on its own state error and never crashes the agent.

The hook enforces the bound and the ramp. It does not measure understanding; it requires that a demonstration was recorded before ambition grows. Measuring understanding is the human's job, which is the entire point: the gate exists so that judgment is built, not bypassed.

Ramp Ledger

A ramp that leaves no trace cannot be audited, and an unauditable demonstration is the Duolingo failure waiting to happen: a cheap signal nobody checks. The ramp ledger records each notch climbed so the demonstration that earned it can be reviewed later, by a different person than the one who produced the increment. This is the four-eyes audit trail applied to the ambition ramp.

What a ledger entry records

One entry per rung climbed, appended when a ramp token is minted:

Where it lives

The guard_scope_ramp.py hook appends one JSON line per notch to .imbue/ramp-ledger.jsonl whenever a token widens the rung, capturing the increment number, the rung before and after, the risk tier, the gate, and a timestamp. That file is gitignored and session-local: it is the raw trail, not the permanent record.

The durable home is the project decision journal, leyline:decision-journal. A ramp entry is a decision with a consequence (the wider rung), so it belongs alongside the tradeoff entries that minted it, not in a separate store. Promote each .imbue/ramp-ledger.jsonl line into the decision journal with the demonstration text filled in (the hook records the structural fields; the human records what was actually asked and answered). The .imbue/ramp-ok token is ephemeral; the journal entry is permanent.

Why the demonstration text is the point

The ledger field that matters is demonstration, and for high-stakes rungs it must be the answer to a novel question about the actual change, not a recap the agent supplied. A reviewer reading the ledger later should be able to tell whether the human understood the increment or rubber-stamped it. If the recorded demonstration could have been written without reading the diff, the gate was gamed and the entry is evidence of it. Record what was actually asked and actually answered, in the human's words.

What the ledger is not

It is not a burndown chart or a velocity metric. Counting rungs climbed and optimizing for more of them per hour reproduces the exact Goodhart failure the gate exists to prevent: the streak that decouples from skill. The ledger is read backward, to audit that each ramp was earned, not forward, to set a pace.

Research Basis: Graduated Implementation

The evidence base behind this skill. The SKILL.md Overview summarizes the load-bearing findings; this module preserves the full tables, failure modes, cross-domain convergence, and citations for auditing the claims.

Thread A: the advancement number is real and converges

Five independent literatures land on the same target band: keep the learner where they succeed most of the time but not all of it, and move the difficulty to hold that point.

The 85% rule is the quantitative spine: it is the same number the ZPD boundary, the edge of ability, and the flow channel all gesture at, derived formally rather than by analogy.

Thread B: the three failure modes are documented with numbers

The Duolingo case is the load-bearing warning: a cheap signal (completion, streak, "tests pass") will be satisfied without the understanding the ladder was built to certify.

Thread C (TRIZ): cross-domain convergence on the gate design

Five high-stakes apprenticeship domains independently resolved "graduate the operator to higher autonomy only when proven, without stalling and without faked readiness":

1. Per-capability, not global. Medical EPAs score each task on a 1-5 supervision scale; driver licensing restricts by context (no night driving) rather than one global dial. Map ambition as a vector of capability-specific levels, simple capabilities advanced first. 2. Externally judged artifact. The guild masterpiece, ABRSM's visiting examiner, and EPA observed milestones all separate the producer from the certifier. This is the four-eyes principle and the universal anti-gaming device: readiness cannot be self-attested. 3. Clean-record gating beats time-served. GDL lifts restrictions only after a conviction-free window; one bad merge resets the clock and can demote a tier. 4. Defeat faked readiness with novelty. ABRSM sight-reading uses an unseen piece; medicine rejected "see one, do one, teach one" because confidence outran competence (28-42% of residents felt unsafe doing a procedure solo the first time). 5. Guard the assistance dilemma directly. Aviation's "children of the magenta": ramp autonomy faster than retained understanding and the operator can no longer hand-fly or override. Countermeasure: mandatory periodic hand-flying.

Dominant TRIZ principles: #15 dynamics, #16 partial action (deliberately under-automate to keep the human in the loop), #23 feedback, #24 intermediary, #25 self-service, #1/#3 segmentation by stakes.

Thread D (code): mechanisms to borrow

Provenance

Originally captured as research session 3dfdba53 (2026-06-02; channels: academic, discourse, code, triz). This pass targeted the gap that session 19c28f3c (see assisted-mastery modules/research-basis.md) opened: a workflow should start with a bounded, intentional implementation and ramp ambition only as the human's understanding of the prior increment is demonstrated.

Sources

Primary: Wilson et al. 2019 (Nature Communications 10:4646, DOI 10.1038/s41467-019-12552-4); Bloom 1968/1984; Keller 1968; Corbett & Anderson 1995; Platanios et al. 2019 (NAACL); Ericsson, Krampe & Tesch-Romer 1993; Bjork & Bjork 1992; Csikszentmihalyi 1990; Doroudi & Brunskill 2017 (EDM); Cen, Koedinger & Junker 2007 (AIED); Baker, Corbett & Koedinger 2004 (ITS); Settles & Meeder 2016 (ACL); Matiisen et al. 2017 (TSCL, arXiv 1707.00183). Cross-domain: AAMC EPAs, "children of the magenta" (Van Der Burgh 1997), graduated driver licensing, medieval guild masterpiece, ABRSM graded exams. Code: pyBKT, py-fsrs, eaplatanios/curriculum, nizos/tdd-guard, Swarmia autonomy levels.