Menu
How a new user becomes a registered teacher — the post-first-feature name capture, the WhatsApp Registration Flow form, and the user fields that gate it.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | registration |
| description | How a new user becomes a registered teacher — the post-first-feature name capture, the WhatsApp Registration Flow form, and the user fields that gate it. |
Up: .claude/CLAUDE.md (config & skills router) · See also: debugging
A new user can talk to the bot and use features before they're "registered". Registration captures their
name (and, via the Flow form, richer profile fields) so later interactions are personalised. There are
two paths, both converging on the same users columns.
handleRegistrationFlow in bot/shared/handlers/flow-response.handler.js.The lightweight path, triggered after the user's first completed feature:
FeatureRegistrationService.checkAndTriggerRegistration(userId, ...) runs after a feature delivers.first_name set or registration_completed = true) or already mid-flow (registration_pending_name = true).countUserFeatures(userId) === 1), sendNameQuestion(...) asks their name in their language and sets registration_pending_name = true.isPendingName(userId) in the text handler → handleNameResponse(...) extracts the name, sets first_name, registration_completed = true, registration_completed_at, and clears registration_pending_name.A richer path using a WhatsApp Flow form. The submission webhook is decrypted by the flow-encryption
service and handled by handleRegistrationFlow in
flow-response.handler.js, which writes the full
profile to the users row and sets the same completion fields. The Flow is identified by a Registration
Flow ID configured in env. (For the Flow plumbing itself — endpoint data exchange, init-values, DRAFT vs
PUBLISHED — see the WhatsApp Flows skill once it lands.)
-- in the users table
first_name -- presence alone counts as "registered"
registration_completed -- boolean; checked FIRST
registration_completed_at -- timestamp
registration_pending_name -- true while waiting for the name reply (path 1)
To force a clean re-registration, reset all of these (a half-reset leaves the user wedged):
await supabase.from('users').update({
first_name: null,
registration_completed: false,
registration_completed_at: null,
registration_pending_name: false,
}).eq('id', userId); // by UUID, never by phone
| Symptom | Cause | Fix |
|---|---|---|
| Registered user re-prompted | A reset left registration_completed = true but first_name null (or vice-versa) | Reset all four fields together. |
| Name reply ignored | registration_pending_name not set, so the text handler doesn't intercept | Confirm sendNameQuestion ran and set the flag. |
value too long for type character varying(N) on a profile field | A Flow field exceeds its column width | Widen the column to fit the real input. |
WhatsApp (#100) error on the prompt | Empty message body sent | Guard against an empty prompt string before sending. |
| Flow submitted but user not updated | Decryption or handler failure | Trace the correlation id through handleRegistrationFlow — see debugging. |
SELECT id, phone_number, first_name, registration_completed, registration_pending_name
FROM users
WHERE registration_pending_name = true
ORDER BY updated_at DESC;
Classroom-observation coaching pipeline — pluggable scoring frameworks (OECD/HOTS/TEACH/FICO), the async queue worker, lesson-plan integration, and session debugging.
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.