メニュー
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;