Skip to content

Editorial Standard — Insight session (psychoeducation card stack)

Purpose

An insight session is a swipeable psychoeducation card stack. Its job is to explain a single mechanism — the habituation model, the anxiety loop, the checking compulsion, why spikes are not permanent worsening — clearly enough that the user gains a concrete mental model and, with it, a degree of agency over their distress. Each session covers one mechanism only; the user finishes knowing something specific they did not know before and understanding what that means for their day. Insight sessions populate the Library tab across six categories (understanding, thoughts, sleep, focus, social, relaxation) and range from 3 to roughly 8 cards depending on the complexity of the mechanism.

Voice register

Default register is early habituation: companion-forward, still, warm (per voice.md contextual tone shifts). The knowledgeable guide is explaining something that matters, not broadcasting wellness advice.

For onset-facing or crisis-adjacent insights (e.g. acute vs. chronic, pulsatile tinnitus, sudden onset) shift to the acute crisis register: more authoritative, maximally specific, orientation before comfort. Name the mechanism first, reassure second. The user in the acute window needs clinical orientation; they do not yet need warmth.

In all registers: honest before hopeful. Name the difficulty, then the path. The mechanism is the comfort — not the other way around.

Evidence / IP

Insight sessions are adaptations of a finished, quality-gated content-automation article — the article → insight-session mapping lives in docs/insight-session-mapping.md. The article is the canonical source.

  • Ground every card in the source article. Each card must faithfully represent what the mapped article states: no claim beyond what the article supports, and preserve the article's hedging. Do not independently re-source primary literature for an insight.
  • Inherit the article's citations, in plain language. Populate the Directus citation field from the source article's citation list, but write it for a patient: keep the study's plain-English name ("a 2024 review of CBT for tinnitus"), never a PMC id, vault note, #NN ref, or link. validate.py hard-fails those. Cards with only mechanism description (no statistic, no named study) still omit the citation.
  • docs/session-content-evidence-base.md, the protocol files (docs/protocols/), and vault notes are background references for authors — not the per-card grounding mandate for educational insights. The backlog row's source_refs (sessions/sessions-backlog.csv) is advisory.

Technique-derived content (breathing / exercises / sounds) still grounds independently in protocols + the evidence base. This article-as-ground-truth rule is specific to article-derived insights.

IP sourcing rules (per docs/session-audio-protocols-ip-guide.md): state mechanisms in plain language; do not reproduce verbatim article or clinical-protocol text; cite by study / programme name in the Directus citation field, not in card copy. The card copy reads as authorial voice, not a literature review.

Length / reading level

Each card: 40–80 words across all paragraphs combined (per docs/insight-session-mapping.md Part 4 target). The footer conventionally reads "90 second read" or "2 minute read" depending on card count.

Reading level: plain language. Aim for Grade 8 or below (Flesch–Kincaid). Concrete nouns, short sentences, no subordinate clauses stacked. The user reading at 11pm during a spike does not have bandwidth for a nested argument.

Card titles should name the mechanism directly ("How habituation actually works", "Why spikes aren't permanent") not describe the format ("Introduction", "What this means for you").

Session-level structure: 3–8 cards for a single mechanism. Fewer than 3 is a tip, not a mechanism explainer; more than 8 usually means you are covering more than one mechanism — split it. (The schema enforces this band: cards minItems 3 / maxItems 8.)

Editorial-required elements

These quality bars go beyond what the schema requires:

  1. Mechanism, not reassurance. The card copy must state why the mechanism operates, not just that things will be okay. "The brain classifies tinnitus as irrelevant through repeated low-threat exposure" is mechanism. "You can feel better over time" is reassurance. Only mechanism produces agency.

  2. Specific, not generic. Every card should contain at least one concrete, grounded statement the user can apply to their lived experience: a specific percentage, a named technique, a recognisable situation. No card should consist entirely of abstract wellness language.

  3. Agency-ending, not reassurance-ending. The final card in a stack must end with what the user can do or understand differently — not with a comfort statement. "This means your goal is not silence — it's reducing the threat response to the sound" closes with agency. "Remember, you are not alone" closes with reassurance. The latter fails.

  4. One mechanism per session. If the draft covers both the habituation model and the checking compulsion, split it. Cognitive overload after one session is a real outcome.

  5. No claim without grounding. Every card must be faithful to the source article. If a card states a statistic or names a study, the Directus citation field must carry it (inherited from the article's citation list). Cards with only mechanism description (no percentage, no named study) can omit the citation.

  6. Obeys ai-patterns-en.md. The card copy must obey all of ai-patterns-en.md — including the no-em-dash punctuation rule and banned constructions — in the produced card copy. In particular: no "journey", no "holistic", no "navigate", no "transformative", no "breakthrough", no wellness-cliché phrasing in the card body (outside the labelled ❌ counter-examples in authoring docs).

Examples

Good — "The Anxiety Loop" (card 2 of 3):

The feedback loop

Tinnitus triggers the threat response. That response sharpens your attention to the sound, which makes it feel louder. Heightened distress makes the threat response fire again. The loop runs on its own fuel.

Breaking it requires reducing the threat value of the sound, not the sound itself. That is what psychological approaches do, and why they outperform sound-only treatment.

Why this works: it names the mechanism precisely (threat response, attention, feedback), uses a specific comparative claim grounded in the source article, and ends with what the user can understand differently (psychological approaches, not sound-only). No clichés, no reassurance, no wellness abstractions. Roughly 65 words.

Bad — counter-example:

❌ Finding your calm

Tinnitus can feel overwhelming, but there are ways to manage your tinnitus and find your peace. With time and the right approach, you can learn to navigate this journey and feel more at ease. You've got this.

Why it fails: "manage your tinnitus", "find your peace", "navigate this journey", and "you've got this" are all banned under ai-patterns-en.md (Naluma-voice additions). The card contains no mechanism — a user who finishes it knows nothing new. It ends on toxic positivity, not agency. It could have been written for any chronic condition without knowing anything about tinnitus.