Skip to Content

Skill-Status Engine

The Skill-Status Engine (SSE) is the deterministic decision pipeline that transforms raw measurement evidence (θ rows from diagnostic sessions, CBM probes, and other evidence types) into interpretable statuses at three levels: per-sub-skill, per-domain, and per-macro-domain tile. Those statuses are the primary input to Student Profiles.

All SSE rules are versioned and published before being frozen. A published rule version is never edited; it is only superseded by a new version. This publish-then-freeze contract is what makes V-6 audit replay possible: a replay run re-executes the exact rule version that was active when the original decision was made.

The 5-layer pipeline

The SSE processes evidence through five sequential layers. Each layer reads only from its inputs and writes only to its designated outputs. There is no back-channel between layers.

Evidence in
    │
    ▼
[ADR] Assessment Decision Rules  (ADR-01..ADR-12)
    │  raw response → Final_Status_Code
    ▼
[FSC] Final_Status_Code          (12 codes)
    │
    ▼
[PAC/CIS] Pattern-Aware Confirmation  (PAC-01..PAC-13 + CIS-01..CIS-04)
    │  confirms or witholds the FSC based on cross-evidence patterns
    ▼
[SSR] Skill_Status_Rules_v2      (SSR-01..SSR-12)
    │  → 9-value SkillStatus + confidence + decision_strength
    ▼
[DDR] Domain_Decision_Rules_v2   (DDR-01..DDR-10)
    │  → 9-value DomainStatus
    ▼
[DSM] Domain_Status_To_Macro_Map (DSM-01..DSM-09)
    │  → macro-domain tile statuses (DSM directly emits 5; Severe via escalation)
    ▼
Status out → Student Profiles

Layer 1: ADR (Assessment Decision Rules)

ADR-01 through ADR-12 classify each response by its behavioural characteristics. They are purely mechanical: given a response record, an ADR rule outputs a Final_Status_Code. No domain logic or pattern context is applied at this layer.

Layer 2: FSC (Final Status Code)

There are 12 Final Status Codes. They are internal identifiers, not exposed in any student-facing or parent-facing surface.

Layer 3: PAC/CIS (Pattern-Aware Confirmation)

PAC rules (PAC-01..PAC-13) check whether the FSC from layer 2 is consistent with the broader evidence pattern for that student and sub-skill. CIS rules (CIS-01..CIS-04) handle the cross-item consistency sub-checks. A PAC rule may confirm the FSC, withhold it pending more data, or trigger the do_not_decide_yet sentinel.

Layer 4: SSR (Skill Status Rules)

SSR-01 through SSR-12 synthesize the confirmed status into the 9-value SkillStatus enum, along with a confidence rating and decision_strength. The 9 SkillStatus values are:

SkillStatusMeaning
adequateSkill is on track
monitorSkill is being watched but not yet a concern
weak_isolatedWeakness in this skill only
monitor_gatewayGateway skill being monitored
weak_gatewayGateway skill is weak
weak_domain_relatedWeakness related to domain pattern
broad_weakness_relatedPart of a broader cross-domain weakness
cautionary_weakness_with_metadataWeakness noted with additional context
contextual_reviewRequires contextual teacher review

Layer 5: DDR and DSM

DDR-01 through DDR-10 aggregate per-skill statuses within a domain into one of the 9 DomainStatus values (same vocabulary as SkillStatus). DSM-01 through DSM-09 then map domain statuses to the macro-domain tile statuses. DSM directly emits five values: Meets, Approaching, Below, Partial, and Contextual. Severe is not a direct DSM output; it is produced only by the two L5 escalation paths described below. Not_Assessed is the rollup default and is never a DSM emission.

How Severe is produced

Severe is never a direct DSM emission. It is produced only by two L5 escalation paths (l5-dsm.ts), per the partner master-answers Q1/Q3 (2026-06-21):

  • Path A — gateway severity: gateway-severity ≥ DTH-SEV-01 on a gateway_driven_domain_concern.
  • Path B — weighted deficit: raw weighted_deficit_rate ≥ DTH-DEF-03 (50%) on a coherent, broad, or gateway domain that has valid evidence.

It is explicitly never count-based and never percentile-based.

DDR-LC: COMP-domain cross-domain refinement (FR-SSE-21)

After the standard DDR run, the COMP (reading comprehension) domain receives an additional cross-domain check against the LISTEN and foundational domain statuses. Four DDR-LC rules (DDR-LC-01..DDR-LC-04) classify the comprehension pattern into one of five CompDiagnosticPattern values:

PatternMeaning
decoding_bottleneckComprehension gap is primarily driven by decoding difficulty
language_bottleneckComprehension gap is primarily driven by language weakness
combined_dual_bottleneckBoth decoding and language contribute
text_strategy_bottleneckEvidence points to a text-strategy gap rather than a foundational one
inconclusive_needs_more_dataCross-domain pattern is unclear; more evidence required

DDR-LC also attaches a compRoutingHint that the intervention bundle recommender reads when selecting a COMP-adjacent bundle. Both fields appear on the domain-status DTO returned by GET /api/sse/students/{id}/domain-status.

The do_not_decide_yet sentinel

do_not_decide_yet is a hard halt. When the SSE emits this sentinel for a student × sub-skill combination, all downstream consumers must short-circuit. The student profile engine, the intervention bundle recommender, the teacher dashboard, and any reporting surface must treat this student as “more data needed”, not as any particular status.

There is no PATCH or override path to clear do_not_decide_yet at the API level. It clears automatically when sufficient evidence accumulates in a subsequent assessment window.

The sentinel is triggered by:

  • Insufficient comparable evidence (GSR-01: fewer than the minimum distinct items scored)
  • Tie-rule conflicts where two equally-weighted evidence sources point in opposite directions and no tiebreaker applies

When do_not_decide_yet is present the API returns nextRecommendedDataAction describing what data collection would resolve the halt.

Response-Behavior Metadata (RBM)

The SSE also collects Response-Behavior Metadata (RBM-00..RBM-11) alongside every scoring run. RBM flags capture a range of administration signals (rapid guessing, repeated same-option selection, teacher context notes, and similar observations). RBM-08 specifically fires when the teacher records a controlled context flag via the context-flag vocabulary (FR-SSE-20). All RBM flags are internal-only: they inform teacher review but never modify a score or status (scoreImpact: None is enforced on every RBM row). They are never shown to students or parents.

Gateway skills and the Arabic-accuracy carve-out

The SSE applies the gateway classification from the Skills Taxonomy at layer DDR. A weak_gateway or monitor_gateway SkillStatus escalates the surrounding domain’s DDR result.

Arabic-accuracy indicator sub-skills (shadda, tanween, madd, short-vowel marking, and related orthographic features) are explicitly excluded from gateway escalation paths (FR-SSE-10 enforces this carve-out). A weakness in one of these skills produces the ARABIC_ACCURACY_ONLY_MONITOR modifier on the student profile rather than a domain escalation.

Versioning and V-6 replay

Rules are published with a version number via a backoffice endpoint. A published version is immediately frozen. No edits are permitted. New rules arrive as a new version. All SSE rule tables (skill_status_rules, domain_decision_rules, domain_status_macro_map) carry a version + @@unique([key, version]) constraint so historical versions remain queryable.

Every SSE output row stamps the ruleVersion it used. The POST /api/sse/admin/dry-run-replay endpoint (backoffice-gated, RUN_BACKOFFICE permission) accepts {studentId, evidenceWindow, proposedVersions?} and re-derives per-skill statuses against the proposed rule versions, writing zero rows. If the derived statuses differ from the stored snapshot, the audit log records a mismatch; this is the V-6 integrity check.

How SSE connects to Student Profiles

The SSE writes per-sub-skill and per-domain status rows. The Student Profile module reads those rows and:

  1. Applies the anti-overlap rules (AO-01..AO-04) to select exactly one primary profile
  2. Attaches modifier profiles (including ARABIC_ACCURACY_ONLY_MONITOR from the carve-out)
  3. Derives sub-flags (AR_MADD_FLAG, VOCAB_ALERT, etc.)
  4. Selects the SPOT narrative template
  5. Returns the profile for teacher review (pending_teacher_review initial status, per V-12)

The measurement bridge

A finished diagnostic triggers projectBridge, which fans out recomputeForEvidence once per sub-skill and then runs recomputeMacroForStudent once. The macro writer (writeMacroSnapshot) lives in this module’s snapshot-writer.ts, so the SSE owns the projection that fills the 6 macro tiles and the GLOBAL meta row at finish. For the trigger chain, the evidence_row shape, the id-key contract, and idempotency see the Measurement Bridge guide.

Key API surfaces

The SSE exposes 5 consumer read endpoints (teacher or admin, VIEW_OWN_CLASSES OR RUN_BACKOFFICE) and 2 admin-only endpoints (RUN_BACKOFFICE). The consumer read surfaces return resolved skill-status snapshots, domain-status snapshots, pattern-classification history, behavior logs, and config rule layers. Admin endpoints publish new rule versions and run dry-run replays.

For the authoritative endpoint list see the API Reference (skill-status-engine tag).

Getting Started