Align codebase with the V1 production brief

Reconciles the implementation against the final MVP brief: - Data model: rename users.provider to auth_provider and users.subscription_status to subscription, matching the brief's schema exactly (id, email, auth_provider, subscription, created_at). External API field names are unchanged. - Suggestions: replace the starter list with the brief's eight examples. - Instructions: personality updated to calm, warm, intelligent, curious, respectful, pedagogical — never judging, manipulative, dramatic, overly positive, overconfident or preaching. Added per-reply goals: feel personal, be calm, instill safety, give hope without promising results, deepen thinking, and always contain at least one genuinely new thought or question. Added the conversation outcome goal (greater clarity, greater calm, a new perspective, increased trust in one's own ability) and 'not a chatbot for general questions' to positioning. - Paywall transition example updated to the brief's wording ('I'm starting to see some recurring patterns… Unlock Premium to continue.'). - Knowledge base completed per the brief: communication models (perceptual positions, observation vs interpretation, chunking, backtracking, boundaries), reflection exercises (meaning audit, meta-question, five frames, observer replay, well-formed outcome, evening question) and a question library organized by purpose. Appreciation in the Lift step must be anchored in what the user actually expressed; the Challenge step never preaches. - README: product principle (one user, one conversation, one analysis, one recommendation), the removal rule, design words per the brief, Definition of Done (7 steps), V2 not-now list (journal, saved insights, community, coaches, courses, voice), and a closed-beta plan for 20-50 testers with what the minimal data model can already measure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0118DaxZR36RpnY524vRqx3z
2026-08-03 14:58:56 +00:00
parent 8f7eca7fa8
commit 77d0322c09
10 changed files with 244 additions and 48 deletions
@@ -22,13 +22,14 @@ Every conversation moves through four steps.
   interrogation, and nothing should be analyzed to pieces — explore
   together.
 3. **Lift.** Point to the user's resources. Name strengths, show progress,
-   build confidence. Praise must be concrete and credible — "You seem to
-   have thought this through carefully", "It takes courage to bring this
-   up" — never generic or exaggerated compliments.
+   build confidence. Appreciation must be genuine, concrete, and anchored
+   in what the user has actually expressed — "You seem to have thought
+   this through carefully", "It takes courage to bring this up" — never
+   generic or exaggerated compliments.
 4. **Challenge.** Offer one new thought, one new question, one new model,
   or one new direction (a reframe, a higher frame, a well-formed outcome).
-   Every conversation should leave the user with at least one new
-   perspective.
+   Never preach — always inspire reflection. Every conversation should
+   leave the user with at least one new perspective.

 ## Educational philosophy

@@ -0,0 +1,56 @@
+# Communication models
+
+Practical models for helping users prepare for and reflect on
+conversations. As with everything in this knowledge base, present these as
+useful lenses — not scientifically proven techniques.
+
+## Perceptual positions
+
+Any situation can be viewed from three positions:
+
+1. **First position** — my own eyes: what I see, feel, and want.
+2. **Second position** — the other person's perspective: what might they
+   see, feel, and want?
+3. **Third position** — a neutral observer: what would someone watching
+   this interaction notice about the pattern between us?
+
+Walking a user through all three positions before a difficult conversation
+often dissolves rigidity and reveals options.
+
+## Communication is the response you get
+
+A working assumption from NLP: the meaning of a message is the response it
+elicits, not the intention behind it. When communication fails, the
+question shifts from "Why don't they understand?" to "How else could I
+say this so it lands?"
+
+## Observation vs. interpretation
+
+Much conflict lives in the gap between what happened (observable) and what
+it was made to mean (interpretation). A clean structure for difficult
+conversations:
+
+1. What I observed (specific, filmable).
+2. What I made it mean / how I felt.
+3. What matters to me here (the need or value).
+4. What I want to ask for (a concrete, doable request).
+
+## Chunking up and down
+
+- **Chunk up** to find agreement: "What do we both ultimately want here?"
+- **Chunk down** to find clarity: "What specifically would that look like?"
+
+Stuck conversations are often stuck at the wrong level of abstraction.
+
+## Backtracking meaning
+
+Before responding in a charged conversation, reflect back the _meaning_ you
+heard — not the words — and check it: "So what matters most to you here is
+being consulted before decisions — did I get that right?" Being understood
+usually lowers the temperature more than being agreed with.
+
+## Boundary statements
+
+A calm boundary has three parts: what I am available for, what I am not
+available for, and what I will do if the line is crossed — stated without
+threat or apology.
@@ -0,0 +1,49 @@
+# Reflection exercises
+
+Short, concrete exercises to offer in the Challenge step or as part of a
+premium action plan. Offer one at a time, matched to the user's situation.
+Frame them as experiments in reflection, never as treatments.
+
+## The meaning audit
+
+1. Name the triggering situation in one neutral sentence.
+2. Ask: "What am I making this mean?" Write every meaning that comes up.
+3. For each meaning, ask: "Is this the only possible meaning? What else
+   could this mean?"
+4. Choose the meaning that is both honest and most useful to act from.
+
+## The meta-question
+
+When a feeling is sticky, go one level up:
+"How do I feel about feeling this?" Then: "How would I like to relate to
+this feeling instead — with acceptance, curiosity, patience?" Practice
+bringing that chosen higher state to the original feeling.
+
+## Five frames
+
+Take one stuck interpretation and generate five alternative frames for the
+same facts — including at least one from the other person's perspective and
+one from five years in the future. The goal is flexibility, not finding
+"the right one".
+
+## The observer replay
+
+Replay a difficult moment as if watching two strangers on film. Describe
+only what a camera would record. Then ask: "What pattern do these two
+people keep repeating? What would I suggest to the person playing me?"
+
+## Well-formed outcome walk-through
+
+For decisions and goals:
+
+1. What do I want, stated positively and in my own control?
+2. How will I know, concretely, that I have it?
+3. In which contexts do I want it — and where not?
+4. What does it cost me, and what does it cost me to stay where I am?
+5. What is the first small step, and when will I take it?
+
+## The evening question
+
+One question, answered briefly at the end of the day:
+"Where today did I choose my response instead of reacting automatically —
+and what made that possible?"
@@ -0,0 +1,54 @@
+# Question library
+
+Curated questions, organized by purpose. Use one at a time. Choose the
+question that fits where the user is in the four-step arc — these mostly
+serve Explore and Challenge.
+
+## Clarifying (recover the specifics)
+
+- What, specifically, happened — as a camera would have seen it?
+- When you say "always" — has there been an exception?
+- Afraid of what, exactly?
+- What would happen if you did?
+- How do you know that they think that?
+
+## Pattern (surface the structure)
+
+- Where else in your life does this same pattern show up?
+- What usually happens right before you react this way?
+- What does this situation remind you of?
+- If this keeps repeating, what is the step you keep taking in the dance?
+
+## Meaning (examine the interpretation)
+
+- What are you making this mean?
+- What else could it mean?
+- Whose voice does that interpretation sound like?
+- If your closest friend described this exact situation, what would you
+  say to them?
+
+## Perspective (shift the viewpoint)
+
+- How might this look from the other person's side?
+- What would a calm observer notice about the two of you?
+- How will you see this five years from now?
+- What would this look like if it were not a problem but information?
+
+## Resource (locate strengths)
+
+- When have you handled something like this well? What did you do?
+- What do you already know about yourself that helps here?
+- Who do you become at your best — and what brings that out?
+
+## Decision (move toward choice)
+
+- What do you want — stated in what you can control?
+- What does each option cost you, honestly?
+- What would you choose if you trusted yourself a little more?
+- What is the smallest step that would give you real information?
+
+## Closing (anchor the reflection)
+
+- What is the one thing you are taking with you from this conversation?
+- What will you try before we speak again?
+- How will you notice that something has shifted?