| name | graduated-implementation |
| description | Ramps implementation ambition a notch only after the prior increment is understood. Use when building a feature you must understand, not just ship. |
| alwaysApply | false |
| category | workflow-methodology |
| tags | ["learning","graduated-practice","zone-of-proximal-development","scope-ramp","competence-gate","automation-bias"] |
| dependencies | [] |
| tools | [] |
| usage_patterns | ["bounded-start","competence-gated-ramp","magenta-hand-fly-check"] |
| complexity | intermediate |
| model_hint | standard |
| estimated_tokens | 2300 |
| modules | ["modules/advancement-gate.md","modules/ramp-ledger.md","modules/research-basis.md"] |
| role | library |
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.
