القائمة
Classroom-observation coaching pipeline — pluggable scoring frameworks (OECD/HOTS/TEACH/FICO), the async queue worker, lesson-plan integration, and session debugging.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Trace any feature end to end — webhook → handler → service → queue → worker → DB → storage → delivery — to find where a user's request actually broke. The map that points you at the right service, worker, table, and skill for each feature.
How the bot logs — structured single-line JSON to the console, correlation IDs that thread a request across handler/queue/worker, semantic events, and an optional external log backend. Use when adding logging or wiring observability.
Pre-merge defensive checks for recurring, predictable bug classes — run before merging code that (a) emits new interactive button/list/Flow IDs, (b) edits or sends a Flow, (c) writes new enum/status values, (d) chains Supabase update+filter+select, (e) sends to a dormant user, or (f) tracks files toxic to a fresh clone. Each class has a concrete grep/SQL pre-flight and the failure mode it prevents.
A/B testing via a Thompson-sampling multi-armed bandit. DB-driven tests (ab_tests / ab_test_variants / ab_test_events) that learn the best-performing variant online. Use when adding or measuring a message/content experiment.
Query the bot's Postgres database with a read-only role. Use when analysing user metrics, debugging DB state, or exploring the schema. Column names: phone_number (not phone), first_name (not name) in the users table.
How testing works in this repo — the test runner, the domain-organised jest suites, the conformance guards that lock the schema/docs/source contracts, and the route-contract pattern for catching orphan dispatch. Use before adding tests or diagnosing CI.
| name | coaching |
| description | Classroom-observation coaching pipeline — pluggable scoring frameworks (OECD/HOTS/TEACH/FICO), the async queue worker, lesson-plan integration, and session debugging. |
Up: .claude/CLAUDE.md (config & skills router) · See also: debugging, digital-coach
The coaching feature takes a teacher's classroom-observation audio, transcribes it, scores it against a pedagogical framework with the LLM, and returns a written + voice report. It runs asynchronously on the queue worker so a long transcription never blocks the webhook.
coaching_sessions table.framework-registry.js plus one module per framework.Scoring is not hard-wired to one rubric. The active framework is chosen at runtime through the registry at frameworks/framework-registry.js:
const FRAMEWORKS = {
oecd: () => require('./oecd-framework'),
hots: () => require('./hots-framework'),
teach: () => require('./teach-framework'),
fico: () => require('./fico-framework'),
};
Each module exports its goal/criterion structure, the marks scheme, and the prompt fragments the LLM
uses. The default oecd framework scores 5 goals across 19 classroom criteria + 4 reflective-debrief
criteria (23 total). To add a region's own rubric, drop a new *-framework.js module and register its key
— no orchestrator changes needed.
Beyond the four registry frameworks, the bot also ships a MEWAKA report path (a Tanzania teacher-CPD
format): when a session's framework is mewaka, the report is rendered by a dedicated transformer +
template rather than the standard renderer — see the framework === 'mewaka' branch in
bot/shared/services/pdf-report.service.js.
The framework used for a given session is recorded inside
coaching_sessions.analysis_data.framework(there is no dedicated column). Each framework writes a differentanalysis_datashape, so always read theframeworkfield first before parsing scores.
coaching_sessions and enqueues a job.QUEUE_DRIVER in bot/CLAUDE.md (sqs default, or bullmq for a Redis-only deploy). Both expose the same surface; the worker code is identical.coaching_sessions.A teacher can attach a lesson plan before the observation. It is extracted by
bot/workers/lesson-plan-extraction.worker.js
(PDF / DOCX / image), and the text is passed into the scoring prompt so the report can comment on
fidelity to the plan — what was planned vs. what the transcript shows was executed. The fidelity block
(score, evidence pairs, strengths, gaps) lands under coaching_sessions.analysis_data.
| Symptom | Where to look |
|---|---|
| Report generated but no voice note delivered | coaching_sessions.voice_feedback_url; confirm the audio uploaded to object storage and the send call succeeded (trace the correlation id — see debugging). |
| "Session not found" / generic error to the user | coaching_sessions.status and the error/stack columns for the failed step. |
| Session stuck in a non-terminal state (>24h) | bot/workers/stale-session.worker.js sweeps these; check for a job that errored after dequeue. |
| Scores look wrong / empty | Read analysis_data.framework, then parse with that framework's shape — a mismatch reads as missing scores. |
SELECT status, COUNT(*) FROM coaching_sessions GROUP BY status;