Readiness Model src/pipeline/readiness.py
After signals are normalised, the readiness module computes a single number: the participant's overall readiness score from 0 to 100. This score is what the governance system uses to make decisions. The pipeline doesn't look at raw signals directly — it reasons entirely from this score and its components.
Live values: When you're logged into the dashboard, threshold values below that say teal are pulled live from the server's current config. A red value means the live config differs from what's documented here — update this section.
Three dimensions of readiness
Overall readiness is a weighted combination of three independently computed scores. Each captures a different aspect of whether the participant is in a state to succeed.
1. Cognitive Readiness — how much mental load is the participant under?
Cognitive Load = IL×0.30 + EL×0.50 + (100−GL)×0.20
IL = Intrinsic Load (task complexity, adjusted for prior web use)
EL = Extraneous Load (interface confusion, wrong clicks, backtracking)
GL = Germane Load (100 minus this inverts it — lower GL score = more load)
Cognitive Readiness = 100 − Cognitive Load. A high cognitive load means the participant's cognitive resources are stretched — they have less capacity to handle errors or unexpected decisions. EL has the highest weight (50%) because it reflects avoidable load — load caused by the interface rather than inherent task difficulty. We can't reduce IL (the task is what it is), but high EL is a signal that the intervention content or approach isn't working.
Effective complexity adjusts IL for experience. IL comes from the task template. But a participant who uses the internet regularly isn't carrying the same intrinsic load as one who doesn't, even on the same task. effective_complexity = IL − (prior_web_use × 10). This adjustment is made once at session creation (template read time) and stored in Redis. It doesn't change mid-session.
GL is null for Session 1 before the survey. Germane load comes from the post-session survey's confidence score. The first time a participant uses AGS, there's no prior survey — GL is null. When GL is null, its 20% weight redistributes proportionally across IL and EL (IL gets 37.5%, EL gets 62.5%). The fallback_formula_used field in the database records when this happened. The temporal service updates GL after each subsequent session's survey is submitted.
2. Motivational Readiness — does the participant believe they can succeed?
Motivational = self_efficacy×0.40 + confidence×0.35 + persistence×0.25
Efficacy 40%
Confidence 35%
Persistence 25%
Self-efficacy — collected at onboarding, stable across sessions
Confidence — from post-session survey, updated by temporal service
Persistence — derived live from the Progression sub-score
If confidence is null (no survey yet), its 35% weight redistributes proportionally to self-efficacy and persistence. Self-efficacy is the most stable measure — it doesn't change between sessions. Confidence captures session-to-session variation in how the participant felt about their last attempt. Persistence is purely behavioural — it's computed from how many setbacks the participant absorbed before stopping.
3. Environmental Readiness — is the participant's context supporting them?
Computed from the Context Fit sub-score. Inputs: connectivity status, language match between participant preference and site content, device orientation (phone flat on a table is a bad sign), and whether signal quality is high enough to trust. When signal_reliability_context is low, environmental readiness is further down-weighted — a signal we can't trust shouldn't influence a governance decision.
Overall Readiness
Overall = cognitive×0.50 + motivational×0.30 + environmental×0.20
Cognitive 50%
Motivational 30%
Environmental 20%
Cognitive readiness carries the most weight because it's the most directly observable from interaction signals and the most actionable — an appropriate intervention can reduce cognitive load. Motivational readiness is partially stable (self-efficacy doesn't change in a session), which is why it's down-weighted relative to cognitive. Environmental readiness is informative but largely outside AGS's control.
Readiness bands and cooldowns
The overall readiness score maps to one of four states. The state determines which governance rules are eligible and what cooldown applies after an intervention.
HIGH 70–100
MODERATE 40–69
LOW 20–39
OVERLOAD 0–19
| State | What it means | Default cooldown | Typical governance outcome |
|---|
| HIGH |
Participant is coping well, making progress, low errors |
15s |
Withhold — preserve autonomy, don't interrupt success |
| MODERATE |
Some struggle signals but the participant is still progressing |
20s |
Delay or light tooltip — watch, not intervene |
| LOW |
Clear struggle signals, errors accumulating, progress slowing |
30s |
Guided prompt or reassurance |
| OVERLOAD |
Participant appears overwhelmed — high errors, fatigue signals, very slow |
45s |
Walkthrough or rest prompt |
After an adaptation is delivered, a cooldown is set in Redis with a TTL. During the cooldown window, background_suppression is active and the governance system exits early (Gate 0c) — no additional intervention fires even if the readiness score is low. This prevents piling interventions on top of each other.
If an adaptation worsened the outcome (errors increased after the intervention), a separate 60-second passive_help_only cooldown is set. Only passive help (explicit button press by the participant) can fire during this window.
What gets written to the database
The readiness module writes four rows per event (asynchronously, off the synchronous pipeline path):
COGNITIVE_STATE
MOTIVATIONAL_STATE
ENVIRONMENT_CONTEXT
READINESS_PROFILE
The COGNITIVE_STATE row includes a cognitive_load_detail JSONB column with every named CL indicator — IL, EL, GL, effective complexity, weights used, and the fallback formula name if one was applied. This is the audit trail for every cognitive load decision.