sales-trainer/project.md

Sales Trainer — Project Requirements

Purpose

Provide realistic, one-shot sales practice against simulated customer personas, with a useful post-chat evaluation and coaching debrief.

Governing documents

• docs/plan.md — legacy product architecture and requirements; authoritative for unchanged product behavior.
• docs/HANDOFF.md — operational constraints, repo/deploy conventions, and safety notes.
• docs/engineering-log.md — prior evidence and project history; not a substitute for current verification.

Requirements

• REQ-001: When a customer decides to try a product, branch into a follow-up scenario rather than concluding the chat immediately.
• REQ-002: Randomize among (a) customer silent after two days and trainee must follow up; (b) customer contacts first after two days; and (c) silent then gone/no response after trainee follows up. Silent notices must have multiple natural variants per supported locale.
• REQ-003: In the gone/no-response case, end as a loss after the trainee's follow-up and provide the usual evaluation/coaching debrief, explaining possible external reasons without presenting guesses as known facts.
• REQ-004: A concluded one-shot persona session must change to a completed state, be unavailable for another chat, and expose a summary/result action rather than a start-chat action. Enforce this in both API and UI.
• REQ-005: Persona generation must expose meaningful progress while analysis runs, including understandable stages and failure/completion states.
• REQ-006: Review end-to-end LLM/server/client timeout behavior for slow models; increase finite, appropriate limits and tests where justified.
• REQ-007: Investigate the previously reported error at the “customer will try” system message; reproduce or identify likely code path from evidence, and fix any confirmed defect.

Constraints

• CON-001: Preserve one-chat-per-user/persona, tenant scoping, transcript allowlists, and latent persona privacy.
• CON-002: Do not read or modify secrets, .env, production data, or credentials.
• CON-003: Do not commit, push, deploy, reset, or stash; these operations are outside this change unless separately directed.
• CON-004: Keep LLM/network work asynchronous where it already is; progress indicators must not expose hidden persona data.
• CON-005: Use Thai-first natural product language; keep the interface professional and accessible.

Prohibitions

• MUST-NOT-001: Do not claim speculative reasons for a customer disappearing as established facts; frame them as plausible possibilities.
• MUST-NOT-002: Do not allow a completed chat to be reopened/resumed or accidentally create a second session.

Acceptance criteria

• AC-001: Tests cover each follow-up branch, randomized notice variants, locale allowlist/serialization, completed-session start/resume/send behavior, and preserved one-shot semantics.
• AC-002: Tests cover progress stages/status serialization and the frontend displays progress during generation and handles failure/completion.
• AC-003: Timeout changes are finite, consistent across LLM calls and hosting/client polling, and regression-tested.
• AC-004: Existing backend suite and frontend unit/build checks pass; independent code review returns no blocking security or logic findings.
• AC-005: Error-path investigation is evidence-based and documented; no unverified production failure is described as reproduced.

Decisions

• DEC-001: try branches into three follow-up outcomes: trainee follow-up→gone/loss; trainee follow-up→hesitant/re-engagement; or customer messages first after two days. Never close at initial try.
• DEC-002: Keep exact generated system notices in the transcript allowlist; any randomized pool must remain safe under existing message sanitization.
• DEC-003: Progress is persisted as bounded, non-sensitive stage metadata on the group record and exposed by the existing group poll API unless inspection proves a safer existing mechanism.

Open questions

• OQ-001: Is the old reported system-message error present in current application logs or reproducible in tests? Investigate without reading secrets or production records.

Requirement change log

• 2026-10-02: Owner refined the prior follow-up behavior: try must randomize among silent (trainee follows up), customer re-engages first, and silent-then-gone; notices should vary; gone is a loss with evaluated coaching. Owner additionally requests stage/button lifecycle correction, live generation progress, finite longer timeouts for slower models, and investigation of the earlier error.