Skip to content

Editorial Standard — coach conversation (and coach module)

  • Directus reference: https://cmsdocs.naluma.space/coach-conversations
  • Manifest entries: naluma-directus/authoring-docs/reference-manifest.json -- multiple blocks, all domain coach-content:
  • received_bubble (Naluma message bubble)
  • reply_chip_row (quick-reply chip row)
  • tag_match (branch splice on prior chip selection)
  • profile_match (branch splice on a static onboarding answer -- see "Personalization with profile_match" below)
  • session_card (deep link to a session)
  • sound_card (reference-resolved sound or album)
  • teaser_card, day_divider, collapsed_days_link, week_strip (structural items)
  • Schema files: naluma-directus/schemas/coach-content/*.schema.json (one per block type)
  • Composition rules (conversation structure, sequencing, slot logic, programme week mapping, branch-and-merge patterns): naluma-app/openspec/specs/coach/spec.md. Do not restate those rules here -- link them and follow them.

Purpose

A coach conversation is the primary daily experience in the Naluma app. Delivered in a chat-like interface as a sequence of received_bubble messages, reply_chip_row selections, branching via tag_match, and embedded session_card / sound_card recommendations, it constitutes the guided coaching session for that day's slot (morning, afternoon, night, or welcome).

The conversation serves as the connective tissue of the programme: it sequences the therapeutic arc week by week, introduces and contextualises sessions, checks in on prior work, responds to the user's state (via chip-selected tags), and maintains the relationship between the user and the coach persona. A conversation that fails as writing -- that is generic, clichéd, or disconnected from the user's known programme stage -- undermines every session it links to.

Conversations are distinguished from coach modules (which are standalone building blocks, reusable across slots) by their slotted structure. But both share the same coach voice standard.

Voice register

Voice register shifts by slot and programme week -- all four contextual tone shifts from voice.md apply in different parts of the conversation cadence:

  • Welcome / onboarding conversations (Week 1 welcome slot): close to acute/authoritative. The newly-diagnosed or recently-distressed user needs orientation before warmth. Name what Naluma is, what the programme does, and what to expect. Do not lead with reassurance.
  • Morning slots (Weeks 1-4): companion-forward habituation. A brief, grounded check-in that sets the day's intention and introduces the session. Not cheerful -- present.
  • Night slots (Weeks 1-4): quieter, stiller habituation register. The day is ending; the user may be dealing with the evening spike. Check in with what is real, not with a pep talk.
  • Spike/setback branches (all weeks): warm-authoritative. The tag_match branch for a user who reports high distress must validate before directing. "That sounds like a hard night" before "here is what tends to help."
  • Progress-acknowledgement moments (specific conversations in Weeks 4, 8, 12): rare, understated lightness. Earned, not celebratory. "You went a whole afternoon. That is not nothing." -- per voice.md.

The coach voice is singular and personal, never institutional. First-person "I" (the coach), second-person "you" (the user). No "we" framing. The coach knows the user's programme week and speaks from that knowledge; it does not pretend ignorance of context.

Evidence / IP

Grounded in docs/session-content-evidence-base.md and docs/protocols/. Key coaching principles that govern conversation content:

  • Counselling as active ingredient: TRT RCT (PMC8632517) found counselling alone achieved over 30% tinnitus impact reduction. Vault note #344: empathic, validating tone in Rogerian person-centred counselling matches directive TRT counselling. The coach conversation is clinically meaningful, not just UI scaffolding -- the empathic tone is as important as the linked sessions.
  • Psychoeducation sequencing: vault note #542 establishes that fear mediates CBT benefit. Psychoeducation before any technique introduction reduces the fear baseline and makes the technique more effective. Conversations in Weeks 1-2 must lead with psychoeducation framing before session recommendations.
  • Programme sequencing: the week-by-week conversation arc follows Naluma's own 12-week structure, modelled on the Beukes iCBT programme (PMC8642102) and Kalmeda's 12-week core. The phase order -- psychoeducation (Weeks 1-2), relaxation (Weeks 3-4), cognitive work (Weeks 5-7), ACT/acceptance (Weeks 8-10), consolidation (Weeks 11-12) -- is Naluma's architecture; Beukes (PMC8642102) is an 8-week/22-module programme and does not define these specific week boundaries. The citation remains valid for noninferiority evidence and cognitive sequencing rationale. Conversations that introduce ACT acceptance content before the CBT cognitive work foundation is in place are out-of-sequence.
  • Engagement: vault note #599 identifies high dropout (21-51%) in digital tinnitus programmes as the primary threat. Coach conversations are the primary engagement mechanism -- they must feel worth opening. Generic, formulaic conversations drive dropout.

IP: all conversation content is Naluma-authored. No protected CBT or ACT programme text is reproduced. The programme structure references the Beukes sequence as a model, not as reproduced content. Motivational techniques draw on publicly available CBT and ACT principles.

Length / reading level

  • Received bubbles: 1-4 sentences each. Short enough to read in a chat-scroll. Long unbroken paragraphs in chat are a UX failure. For longer narrative sequences, break into multiple sequential bubbles with leading_space: true between them.
  • Conversation total length: 300-600 words of bubble text across the full conversation (morning/night slots). Welcome conversations may run longer (up to 800 words). The user reads this in a chat interface -- not a document.
  • Reply chip row labels: 3-8 words. Must cover the realistic range of the user's states without implying which is correct. For a check-in on how the previous day went: "Hard. The spike was rough." / "Manageable -- I had a tough moment." / "Better than I expected." -- all are valid.
  • Session card / sound card placement: one embedded session card per conversation is standard. Two is the maximum. Cards appear after the relevant conversational context that motivates the session -- not as openers.
  • Reading level: Grade 8 or below for bubble text. Chip labels Grade 6 or below.

Editorial-required elements

  1. Conversations must reflect programme week. A Week 1 conversation that uses ACT defusion language ("notice the thought, let it pass") before defusion has been introduced is a sequencing error. Conversations must reference only concepts and sessions the user has already encountered or that the current conversation is introducing for the first time.

  2. Branching must reflect real states. reply_chip_row chips and their tag_match branches must cover the realistic range of user responses, including the hard ones. A check-in with only positive option paths ("I feel better" / "I feel much better") fails the user who is struggling. Every check-in must have a branch for distress or difficulty.

  3. Validating branches must validate before directing. In a tag_match branch for high-distress chips, the first received_bubble after the branch splice must acknowledge the user's state before introducing a session or technique. Jumping straight to "here is a breathing exercise" without acknowledgement feels dismissive.

  4. Session cards appear after motivation, not before. The conversation earns the session recommendation by naming a relevant difficulty, explaining why the session helps, then presenting the card. A conversation that opens with a session card has skipped the coaching.

  5. The coach voice is singular. Every bubble should sound like the same person. Conversations written in sections by different authors need an editorial pass to unify voice. Common failures: register shifts mid-conversation; a coaching-heavy opening followed by a generic close; "how are you feeling?" when the chip row already captured the answer.

  6. Obeys ai-patterns-en.md. All bubble text and chip labels must obey ai-patterns-en.md. Coach conversations are the most-read content in the app and the highest-risk place for AI-writing patterns to appear at scale -- review every conversation against the ban list before publishing. In particular: no em dashes in bubble copy, no "navigate", "journey", or "transformative", no toxic positivity in progress-acknowledgement bubbles.

  7. Arc bridge (morning/night). Where the schedule supports it, a morning conversation opens with a programme-framed look-back + today's focus, and a night conversation closes with a one-line outlook to tomorrow. Bridges reference offered/programme content, never assert the user completed anything (no runtime signal). The how is in coach-conversation-craft.md §1.

Push notification (push:)

Every slotted conversation carries a push body -- the initiation that brings the user back to the slot. It is authored in frontmatter, not items[]:

---
type: coach_conversation
conversation_id: w01d1-am
push:
  body: "Two minutes to set today's intention before the day starts."
---
  • Required for every conversation except day-0 (welcome), which is exempt (its push is never delivered -- the push Edge Function's audience floor is schedule day 1).
  • One sentence, ≤140 chars. Same banned-pattern / em-dash / cliché rules as bubble copy; double-quote any body containing :.
  • Per-locale: re-author push.body in each items/<id>.<locale>.md sibling (not inherited from EN).
  • Canonical store is content.coach_schedule.push (publish writes it). Never author push_copy (legacy).
  • How to write it well (specific-not-generic, honest, the slot register): the craft guide §4 push rubric.

Personalization with profile_match

profile_match branches a conversation on a static onboarding answer the user gave at sign-up, instead of a chip they tap in the moment. It is the structural twin of tag_match -- source plus branches: {key -> items[]} -- but it resolves at conversation load against the user's onboarding profile, before the user does anything. Use it to fine-tune the first two weeks to what the app already knows: the user's main difficulty, how recently the tinnitus started, whether they have seen a doctor, and the self-reported type.

The four source variables and their values (the only four):

source meaning values
pain_point the user's main difficulty sleep, concentration, emotional, social
onset how long they have had tinnitus thisWeek, under3Months, 3to12Months, overYear
doctor whether they have seen a doctor yes, notYet
tinnitus_type self-reported type subjective, objective, dontKnow

The wire shape (the JSON block) lives in naluma-directus/schemas/coach-content/ -- link it, do not restate it here.

Rules:

  • _default is mandatory. A profile_match resolves silently at load. If the user's value is null or unknown (onboarding skipped or incomplete), or you did not author a branch for their value, the app uses _default; a missing _default silently drops content. Write _default as the complete, standalone-valid version that works for everyone, then specialise the named branches.
  • Branch keys must be exact enum values for that source (the table above). There is no grouping (onset "recent") -- repeat the body across the relevant keys or fold them into _default.
  • It nests freely with tag_match. A profile_match branch may contain a tag_match, and a tag_match branch may contain a profile_match: personalise the framing by static profile, then still branch on the user's in-the-moment chip.
  • It is not a terminator. Like tag_match, every branch must rejoin a valid terminator; a conversation (or branch) must not end on a profile_match.
  • Static facts only. Use profile_match for what was true at onboarding (difficulty, onset, doctor, type). Use tag_match for how the user feels right now (the chip they just tapped). The app has no runtime signal for present state beyond the chip -- do not reach for profile_match to read it.
  • Personalise the framing, never the safety net. profile_match tailors the opening, the rationale, or which difficulty you name first. It does not replace the distress branch (Editorial-required element 2): a check-in still needs a tag_match path for the hard states regardless of profile.

Good -- profile-personalised opener (profile_match on pain_point, with a _default):

[pain_point = sleep] The nights are often where tinnitus is loudest. Tonight we set up for sleep.

[pain_point = concentration] Focus is where tinnitus tends to intrude most. Let's work with attention today.

[_default] Tinnitus shows up differently for everyone. Here is where we start.

Why this works: the named branches lead with the difficulty the user told us matters most, so the opening feels written for them; _default is a complete opening on its own, so a user with unknown onboarding still gets a coherent start. The personalisation is in the framing -- the session that follows, and any distress check-in, are unchanged.

Examples

Good -- night-slot spike branch (tag_match branch for "Hard. The spike was rough."):

That sounds like a hard night.

Spikes at this stage can feel like the whole pattern is getting worse. It is not -- spikes are highly variable and do not indicate a trend. But that doesn't make them easier in the moment.

This session takes about three minutes. It targets the nervous system's threat response, not the sound.

[session_card: crisis breathing session]

Why this works: the first bubble validates without minimising ("hard night"). The second bubble names the distorted thought the user is likely having ("getting worse"), corrects it with a specific mechanism (spikes are variable, not a trend), and acknowledges the limitation ("doesn't make them easier"). The third bubble frames the session concretely (three minutes, targets the threat response). No wellness clichés, no toxic positivity.

Bad -- morning check-in bubble sequence:

❌ Good morning! We hope you're ready to continue your wellness journey and manage your tinnitus today. Remember: you've got this! Take a moment to find your inner calm with today's session.

[session_card]

Why it fails: "wellness journey", "manage your tinnitus", "you've got this", and "find your inner calm" are all banned under ai-patterns-en.md (Naluma-voice additions). "We hope" uses institutional "we" -- banned (voice is singular). The session card is presented before any motivation or context -- the conversation skips the coaching entirely. "Good morning!" as an opener is a formulaic opener banned under the Naluma-voice additions.