Skills Taxonomy

The skills taxonomy is the canonical reference table that every other subsystem in Amal anchors on. It is a read-only catalogue of 79 sub-skills organised into 9 domains, with gateway classification, dependency mapping, and weight-type derivation. The taxonomy does not change at runtime; it is seeded from the partner workbook (Arabic_Reading_Skills_Assessment_Mapping_v3_3.xlsx, Skills_Master_Table sheet, 79 rows) and is the same for every organisation.

What it contains

79 sub-skills

Each sub-skill row carries:

skillWeightType is not stored; it is computed deterministically from the taxonomy row on every read. The three values are GATEWAY, SUPPORTING, and FOUNDATIONAL.

9 domains

These domains map upward to the 6 macro-domain tiles (READ_FOUND, ACC_FLU, READ_COMP, LISTEN_COMP, LANG_COMP, WR_SP) plus the GLOBAL meta-tile used for cross-domain aggregation.

Wave 1 active skills

Wave 1 measures reading, comprehension, morphology, and vocabulary sub-skills (Grades 1-4). Writing and Spelling (WR_SP domain) items will enter the bank in Wave 2. The API still returns all 79 rows; consumers filter by gradeFrom / gradeTo and domain to determine applicability.

Gateway classification

A gateway skill is one whose weakness cascades. If a student is weak in a gateway skill, the Skill-Status Engine may escalate the domain status for connected downstream domains; a gateway weakness is not just about the skill itself, it shapes the intervention recommendation.

Arabic-accuracy indicator skills: the carve-out

A subset of skills are classified as Arabic-accuracy indicators: these cover features such as shadda, tanween, madd, and short-vowel marking. These skills are never treated as standalone gateway escalations. A weakness in an Arabic-accuracy indicator routes to the ARABIC_ACCURACY_ONLY_MONITOR modifier profile rather than triggering a gateway domain escalation.

This carve-out is enforced in the Skill-Status Engine (FR-SSE-10) and cannot be overridden at the API level. It exists because these features are orthographic and pronunciation markers: their measurement requires written or visual items specifically, and they should not be interpreted as evidence of a broader reading difficulty in isolation.

An additional constraint: no Arabic-accuracy sub-flag may be derived from ORF or CBM data. Flags such as AR_MADD_FLAG and AR_SHORT_VOWEL_FLAG fire only from written/visual item responses. Hamza is out of scope entirely in Wave 1.

Skill dependencies

GET /api/skill-dependencies returns the skill dependency graph. In Wave 1 this returns an empty array; the dependency map is structurally present but the graph is not yet populated pending partner input. The endpoint shape is stable so consumers can build against it now.

The 4 taxonomy endpoints

VIEW_OWN_PROFILE is held by all 6 personas (effectively authenticated-only), but the permission gate is explicit. The taxonomy is global reference data: requireTenantContext runs in the middleware chain for uniformity, but responses are never filtered by organizationId.

Filtering and embedding

GET /api/sub-skills accepts domainId, macroKey, and isGateway query parameters for narrowing the list. GET /api/sub-skills/{id} supports ?include=taxonomy,dependencies to embed the full taxonomy row and any dependency edges.

# List all gateway skills in the Reading Comprehension domain
curl "https://localhost:3000/api/sub-skills?domainId=READ_COMP&isGateway=true" \
  -H "Authorization: Bearer <accessToken>"

How the taxonomy connects to other subsystems

The taxonomy is the static foundation every dynamic subsystem reads from:

• Diagnostic sessions: each item in the item bank carries a subSkillId FK into this table. The engine scores one sub-skill at a time.
• Skill-Status Engine: applies the gateway flag and Arabic-accuracy carve-out rules (ADR, SSR, DDR layers) using isGateway and skill membership to decide escalation paths.
• Intervention Bundles: primaryAnchorSkillGroup in each bundle maps to a domain or skill group drawn from this taxonomy.
• Progress Monitoring: per-bundle monitoring rules (PMR-001..PMR-012) reference specific skill groups from the taxonomy.
• Standards & Benchmarks: benchmark profiles are keyed by skillId from this table.

Related subsystems

• Skill-Status Engine: reads and applies the taxonomy rules
• Intervention Bundles: maps taxonomy skill groups to bundles
• Diagnostic & Practice: items are tagged by sub-skill
• Glossary: definitions for gateway skill, sub-skill, macro domain, and related terms