[Call for Ideas] Persona & Prompt Suggestions for AI Reflection Letters

Read docs/ux-ai-reflection-letters.md and docs/feature-ai-integration.md first, then review api_internal/routes/ai.ts and src/components/letterbox/letter-box.tsx for the current persona, prompt, edge-case, and localization behavior. Done means submitting a focused, actionable suggestion that fits the documented guardrails and identifies the lens, persona, tone, scenario, or language nuance it improves.

One of the most rewarding retention features in Scripture Habit is the AI Reflection Letter (LetterBox). When a user posts at least 2 study notes, a personalized letter is generated from the perspective of a scriptural figure, validating their efforts and connecting their insights to eternal truths.
We are looking for community suggestions to make these letters even better!

Related Documentation and Code

Current Architecture

Model & Generation

• Model: gemini-3.1-flash-lite-preview with thinkingLevel: "minimal" for speed
• Output Format: Structured JSON ({ "title": "...", "letter": "..." }) with robust fallback parsing
• Persistence: Dual write to users/{uid}/letters (LetterBox) + users/{uid}/recaps with TTL: 30 days
• Cooldown: Requires 2+ new notes since the last generation; otherwise returns cached letter

Current Design & Persona System

Persona Pool

The AI selects a scriptural figure from this pool (Jesus Christ is never selected as a persona):

Persona Selection Logic

1. Priority 1 (Direct Match): If the user's notes study a specific chapter authored by or featuring a figure (e.g., 1 Nephi → Nephi, D&C 25 → Emma Smith, Exodus → Moses), that figure is chosen.
2. Priority 2 (Thematic Match): Otherwise, the figure whose personal life experiences best resonate with the user's spiritual topic is selected (e.g., repentance → Alma the Younger, trials → Joseph in Egypt, quiet prayer → Eliza R. Snow).

Multifaceted Persona Angle

Each persona is NOT portrayed as a flat stereotype. The AI selects the specific life episode, emotional state, or struggle that best matches the user's notes and chosen lens. For example, Nephi alone could appear as:

• Lens 1: Broken bow panic and family frustration
• Lens 2: 2 Nephi 4's psalm of weeping & rejoicing
• Lens 3: Metallurgical ship-building ingenuity
• Lens 4: Walking into dark Jerusalem night without prior knowledge

4 Everyday Lenses (Emotionally Adaptive)

The AI dynamically chooses ONE dominant lens based on the user's emotional state and content:

Two-Phase Emotional Progression

Every letter follows a natural arc shaped by the chosen lens:
Phase 1: Warm Icebreaker & Relatable Human Touch

Opens with warmth, empathetic humor, or relieving reassurance. The persona shares their own awkward moments or failures (e.g., Peter sinking in water, Jonah fleeing to Tarshish, Alma passing out). This relieves pressure and creates instant human connection.
Phase 2: Sincere, Christ-Centered Reflection
Transitions into a reverent, emotionally moving reflection. Deeply validates the user's personal efforts, connects their insights to eternal truths, and bears witness of the Savior's love and grace. No jokes in this sacred core.
Poem & Sign-off
Includes a short 3-4 line uplifting poem (clean text, no markdown symbols), a warm blessing, optional witty P.S., and a transparency disclaimer.

Edge Case Handling

Guardrails & Standards

All prompts enforce strict alignment with General Handbook 38.8.47 ("Appropriate Use of Artificial Intelligence"):

1. Christ as Sacred Center: Jesus Christ is NEVER a persona or the subject of jokes
2. Transparency: Opening and sign-off explicitly identify AI roleplay
3. Disclaimer: Every letter includes a spiritual guidance notice
4. Priesthood Boundaries: No speculation on unrevealed mysteries, no pronouncing forgiveness, no judging worthiness
5. Professional Boundaries: No medical, mental health, legal, or financial advice
6. Temple Sacredness: No specific temple ordinance details or confidential covenants
7. Word of Wisdom Compliance: No coffee, tea, alcohol, or tobacco — even in metaphors (use water, meals, walks, fresh air instead)
8. Agency & Correct Principles: Teach principles, honor agency, avoid rigid micro-rules
9. Respect for All Faiths: Uphold the 11th Article of Faith spirit
10. Hope Over Fear: Focus on spiritual courage and Christ's promised return, never incite anxiety
11. Accessible & Dignified Tone: Natural language suitable for youth and all ages

What We Are Looking For

New Persona Suggestions

Know a scriptural figure whose unique life experiences would make for powerful, relatable letters? Suggest them along with which lens(es) they'd excel at!

Prompt & Tone Improvements

Have ideas for making the icebreaker warmer, the Christ-centered reflection deeper, or the poems more touching?

4 Everyday Lenses — New Ideas

Have a new lens perspective that could add variety and emotional range?

Edge Case Scenarios

Encountered a note type or emotional situation where the current system could respond better?

Localization / Cultural Nuance

How can we make these letters feel more natural and culturally engaging in different languages? Currently supported: en, ja, ko, zho, es, pt, vi, tl, th, sw, it