From ee88a94750971735e669f55699016a0720b913cd Mon Sep 17 00:00:00 2001 From: null Date: Thu, 25 Jun 2026 11:37:10 -0500 Subject: [PATCH] =?UTF-8?q?docs(seed):=20split=20question=20guide=20into?= =?UTF-8?q?=20three=20documents=20=E2=80=94=20content=20guide,=20schema,?= =?UTF-8?q?=20rewrite=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- seed/questions/QUESTION_CONTENT_GUIDE.md | 992 ++++++----------------- seed/questions/QUESTION_REWRITE_PLAN.md | 139 ++++ seed/questions/QUESTION_SCHEMA.md | 425 ++++++++++ 3 files changed, 831 insertions(+), 725 deletions(-) create mode 100644 seed/questions/QUESTION_REWRITE_PLAN.md create mode 100644 seed/questions/QUESTION_SCHEMA.md diff --git a/seed/questions/QUESTION_CONTENT_GUIDE.md b/seed/questions/QUESTION_CONTENT_GUIDE.md index c7eec5ba..98d74932 100644 --- a/seed/questions/QUESTION_CONTENT_GUIDE.md +++ b/seed/questions/QUESTION_CONTENT_GUIDE.md @@ -2,11 +2,10 @@ ## Purpose -This guide defines how Closer question packs should be written, reviewed, and validated. +This guide defines the writing philosophy, voice, and tone for Closer question packs. It answers *how* questions should sound and *why*. -Closer is a private couples app. The questions should help two people feel closer through honest, warm, simple conversation. The app should not sound robotic, clinical, cheesy, judgmental, or like therapy homework. - -Use this guide before writing or rewriting any question JSON file. +For JSON schema and validation rules, see `QUESTION_SCHEMA.md`. +For the active rewrite plan and category order, see `QUESTION_REWRITE_PLAN.md`. --- @@ -43,19 +42,19 @@ A good Closer question should sound like something a real person could comfortab Bad: -```text +``` What boundary around money boundaries would help you feel respected? ``` Better: -```text +``` What money boundary would help you feel more respected? ``` Best: -```text +``` What is one money habit we could agree on that would make things feel calmer between us? ``` @@ -65,14 +64,12 @@ What is one money habit we could agree on that would make things feel calmer bet Every question should pass this test: -```bat -ECHO Would a real couple actually answer this? -ECHO Is it clear in one read? -ECHO Does it sound natural out loud? -ECHO Does it invite honesty without blaming either partner? -ECHO Does it fit the pack topic? -ECHO Does it avoid sounding like AI generated filler? -``` +- Would a real couple actually answer this? +- Is it clear in one read? +- Does it sound natural out loud? +- Does it invite honesty without blaming either partner? +- Does it fit the pack topic? +- Does it avoid sounding like AI generated filler? If the answer is no, rewrite it. @@ -82,58 +79,185 @@ If the answer is no, rewrite it. Questions should create moments like: -```text -Oh, that is easy to answer. -That actually sounds like us. -I never thought to ask that. -That feels safe to say. -That could start a good conversation. -That makes me want to see my partner's answer. -``` +- "I didn't know that." +- "Really?" +- "That's adorable." +- "We should do that." +- laughter +- flirting +- nostalgia +- future plans Questions should not create moments like: -```text -What does this even mean? -Why is this worded so strangely? -This feels like therapy homework. -This sounds too intense. -This sounds too sexual too fast. -This feels repetitive. -This makes me feel accused. -``` +- "What does this even mean?" +- "Why is this worded so strangely?" +- "This feels like therapy homework." +- "This sounds too intense." +- "This sounds too sexual too fast." +- "This feels repetitive." +- "This makes me feel accused." --- -# 4. Category Purpose +# 4. Fun-First Rule + +Most Closer questions should feel enjoyable to answer. + +That does not mean every question has to be silly, flirty, or light. Some packs cover serious topics like boundaries, trust, money, conflict, sex, and repair. But even serious packs should not feel like homework, interrogation, therapy intake forms, or emotional labor. + +The user should usually feel one or more of these after answering: + +- Interested +- Amused +- Comforted +- Wanted +- Understood +- Curious +- Relieved +- Closer + +A Closer question should avoid making users feel: + +- Accused +- Tested +- Pressured +- Drained +- Embarrassed in a bad way +- Like they are doing therapy homework +- Like they are about to start a fight + +## Fun-First Balance by Pack Type + +Use this as the default balance unless the pack has a special reason to be different. + +| Pack type | Light / playful / easy | Meaningful / practical | Deeper | +|---|---:|---:|---:| +| Fun, Date Night, Home Life | 60-70% | 20-30% | 10% | +| Boundaries, Trust, Conflict | 30-40% | 40-50% | 10-20% | +| Sex, Desire, Physical Intimacy | 40-50% | 30-40% | 10-20% | +| Money, Future, Values | 35-45% | 40-50% | 10-15% | + +## Fun Does Not Mean Shallow + +A fun question can still reveal something real. + +Weak: + +``` +What is your favorite color? +``` + +Better: + +``` +What color would you pick for a room that felt like us? +``` + +Weak: + +``` +What food do you like? +``` + +Better: + +``` +What meal would instantly make a night together feel better? +``` + +Weak: + +``` +What date sounds fun? +``` + +Better: + +``` +What is a low-effort date that would still make you excited to see me? +``` + +## Serious Does Not Mean Heavy + +Even serious topics should be written in a way that feels safe and answerable. + +Too heavy: + +``` +What unresolved emotional wound affects our relationship dynamic? +``` + +Better: + +``` +What is one thing we could handle more gently with each other? +``` + +Too confrontational: + +``` +What do I do that makes you not trust me? +``` + +Better: + +``` +What small action helps you feel more secure with me? +``` + +Too clinical: + +``` +What communication structure would support healthier conflict resolution? +``` + +Better: + +``` +When we disagree, what helps us slow down before it turns into a fight? +``` + +## Fun-First Review Questions + +Before finalizing a pack, ask: + +- Would this pack feel enjoyable to open after a long day? +- Are there enough easy questions to keep users from feeling drained? +- Would a couple want to compare answers? +- Does the pack include curiosity, play, warmth, or sweetness? +- Are the deeper questions spaced out enough? +- Does the pack still feel like Closer, not therapy homework? + +If a pack feels too heavy, add more light, playful, practical, or curiosity-based questions. + +--- + +# 5. Category Purpose Every pack needs a clear purpose. Before writing a pack, define: -```bat -SET PACK_NAME= -SET PACK_PURPOSE= -SET USER_FEELING= -SET RELATIONSHIP_OUTCOME= -SET FREE_VALUE= -SET PREMIUM_VALUE= -``` +- PACK_NAME= +- PACK_PURPOSE= +- USER_FEELING= +- RELATIONSHIP_OUTCOME= +- FREE_VALUE= +- PREMIUM_VALUE= Example: -```bat -SET PACK_NAME=Date Night -SET PACK_PURPOSE=Help couples plan, enjoy, and remember time together. -SET USER_FEELING=Playful, wanted, relaxed, connected. -SET RELATIONSHIP_OUTCOME=More intentional time together without pressure. -SET FREE_VALUE=Easy, fun, low-pressure date questions. -SET PREMIUM_VALUE=Deeper romance, planning preferences, rut-breaking, and memory-making prompts. -``` +- PACK_NAME=Date Night +- PACK_PURPOSE=Help couples plan, enjoy, and remember time together. +- USER_FEELING=Playful, wanted, relaxed, connected. +- RELATIONSHIP_OUTCOME=More intentional time together without pressure. +- FREE_VALUE=Easy, fun, low-pressure date questions. +- PREMIUM_VALUE=Deeper romance, planning preferences, rut-breaking, and memory-making prompts. --- -# 5. Question Depth Levels +# 6. Question Depth Levels Use depth intentionally. @@ -143,7 +267,7 @@ Light questions should be easy, fun, and low-pressure. Examples: -```text +``` What is a simple date we could do with almost no planning? What snack would make a movie night feel complete? Would you rather go out for dessert or stay in with a blanket? @@ -155,7 +279,7 @@ Medium questions should reveal preferences, needs, feelings, or patterns. Examples: -```text +``` What makes a night together feel special instead of routine? What helps you feel like I really want to spend time with you? What is one thing that would make date night easier for us to follow through on? @@ -167,7 +291,7 @@ Deep questions should invite vulnerability without pressure or blame. Examples: -```text +``` When have you felt most wanted by me, and what made it feel that way? What kind of attention from me makes you feel closest? What do you miss about the way we used to spend time together? @@ -175,220 +299,18 @@ What do you miss about the way we used to spend time together? ## Depth rules -```bat -ECHO Light questions should not feel shallow or useless. -ECHO Medium questions should not feel like a confrontation. -ECHO Deep questions should not feel like a trap. -ECHO Sensitive questions should never pressure a partner to disclose, forgive, explain, or perform. -``` +- Light questions should not feel shallow or useless. +- Medium questions should not feel like a confrontation. +- Deep questions should not feel like a trap. +- Sensitive questions should never pressure a partner to disclose, forgive, explain, or perform. --- -# 6. Question Types - -Each question type should have a purpose. - -## written - -Use for stories, memories, reflection, emotional honesty, and open-ended answers. - -Good written examples: - -```text -What is one small thing I do that makes you feel cared for? -What is a memory of us that still makes you smile? -What is something you wish we made more time for? -``` - -Avoid written questions that are too vague: - -```text -How can we deepen our connection? -``` - -Better: - -```text -What is one thing we could do this week that would make us feel more like a team? -``` - ---- - -## single_choice - -Use for preferences and simple decisions. - -Good single-choice example: - -```json -{ - "type": "single_choice", - "text": "Which kind of date sounds best this week?", - "options": [ - { "id": "cozy_at_home", "text": "Cozy at home" }, - { "id": "dinner_out", "text": "Dinner out" }, - { "id": "something_playful", "text": "Something playful" }, - { "id": "something_outside", "text": "Something outside" }, - { "id": "surprise_me", "text": "Surprise me" } - ] -} -``` - -Rules: - -```bat -ECHO Options should be short. -ECHO Options should not overlap too much. -ECHO Options should sound like real choices. -ECHO Avoid more than 6 options unless truly needed. -``` - ---- - -## multi_choice - -Use when more than one answer can be true. - -Good multi-choice example: - -```json -{ - "type": "multi_choice", - "text": "What helps you feel relaxed on a date with me?", - "options": [ - { "id": "no_rushing", "text": "Not feeling rushed" }, - { "id": "phones_away", "text": "Putting phones away" }, - { "id": "good_food", "text": "Good food" }, - { "id": "easy_conversation", "text": "Easy conversation" }, - { "id": "physical_affection", "text": "Physical affection" }, - { "id": "clear_plan", "text": "Having a plan" } - ] -} -``` - -Rules: - -```bat -ECHO Multi-choice prompts should say or imply that multiple answers are okay. -ECHO Options should not shame either partner. -ECHO Include practical and emotional options when possible. -``` - ---- - -## scale - -Use for comfort level, closeness, energy, readiness, satisfaction, or frequency. - -Good scale example: - -```json -{ - "type": "scale", - "text": "How much do you feel like we need a real date soon?", - "scale": { - "min": 1, - "max": 5, - "min_label": "Not much", - "max_label": "Very much" - } -} -``` - -Rules: - -```bat -ECHO Scale labels should be gentle and neutral. -ECHO Do not make the low end sound bad or shameful. -ECHO Scale questions should measure one thing only. -``` - -Bad: - -```text -How badly are we failing at making time for each other? -``` - -Better: - -```text -How much would some intentional time together help us right now? -``` - ---- - -## this_or_that - -Use for fast, playful, low-pressure choices. - -Good this-or-that examples: - -```text -Planned date or spontaneous date? -Dress up or stay cozy? -Cook together or order in? -Sunset walk or late-night drive? -``` - -Rules: - -```bat -ECHO This-or-that prompts should be quick. -ECHO Avoid choices that imply one partner is wrong. -ECHO Best used in fun, date, intimacy, home, and lifestyle packs. -``` - ---- - -# 7. Free vs Premium Strategy - -Free questions should prove the app is worth using. - -Premium questions should feel deeper, more specific, more personalized, more playful, or more valuable. - -## Free questions should be: - -```bat -ECHO Easy to answer. -ECHO Warm and useful. -ECHO Good enough to create trust. -ECHO Low-pressure. -ECHO Representative of the pack. -``` - -## Premium questions should be: - -```bat -ECHO More specific. -ECHO More thoughtful. -ECHO More emotionally useful. -ECHO More creative. -ECHO More likely to start a meaningful conversation. -``` - -Premium must not be only “more of the same.” - -Bad premium strategy: - -```text -Free: What date sounds fun? -Premium: What date sounds really fun? -``` - -Better premium strategy: - -```text -Free: What is a simple date we could do this week? -Premium: What kind of date would make you feel pursued, not just scheduled? -``` - ---- - -# 8. Banned or Overused Phrases +# 7. Banned or Overused Phrases Avoid these unless there is a very good reason. -```text +``` What boundary around... hold space emotional container @@ -413,31 +335,31 @@ Use natural language instead. Instead of: -```text +``` How can I hold space for your needs? ``` Use: -```text +``` When you are having a hard day, what helps you feel supported by me? ``` Instead of: -```text +``` How can we deepen intentional intimacy? ``` Use: -```text +``` What is one small thing that makes you want to be closer to me? ``` --- -# 9. Tone Rules by Pack Type +# 8. Tone Rules by Pack Type ## Fun packs @@ -445,7 +367,7 @@ Should feel light, playful, and easy. Use: -```text +``` What is a tiny adventure we could do without spending much? What inside joke of ours still makes you laugh? What would make an ordinary night feel more fun? @@ -453,7 +375,7 @@ What would make an ordinary night feel more fun? Avoid: -```text +``` How can we optimize shared leisure experiences? ``` @@ -465,7 +387,7 @@ Should feel romantic, playful, practical, and low-pressure. Use: -```text +``` What kind of date would feel easy but still special? What would make you feel like I planned the night with you in mind? What is one date we keep talking about but never actually do? @@ -473,7 +395,7 @@ What is one date we keep talking about but never actually do? Avoid: -```text +``` What date structure would best support our connection goals? ``` @@ -485,7 +407,7 @@ Should feel respectful, calm, and non-accusing. Use: -```text +``` What is one thing you wish we handled more gently? When you need alone time, what helps you feel understood instead of distant? What is a small boundary that would make our home feel calmer? @@ -493,7 +415,7 @@ What is a small boundary that would make our home feel calmer? Avoid: -```text +``` What boundary around boundaries would support emotional safety? ``` @@ -505,7 +427,7 @@ Should feel safe, repair-focused, and not blaming. Use: -```text +``` When we disagree, what helps you stay open instead of shutting down? What is one thing I can do during an argument that would help us slow down? What helps you feel like we are on the same team again? @@ -513,7 +435,7 @@ What helps you feel like we are on the same team again? Avoid: -```text +``` What do I always do wrong during conflict? ``` @@ -525,7 +447,7 @@ Should feel careful, honest, and non-punishing. Use: -```text +``` What small action helps you trust me more? What makes an apology feel real to you? What helps you feel reassured without feeling like you had to ask too much? @@ -533,7 +455,7 @@ What helps you feel reassured without feeling like you had to ask too much? Avoid: -```text +``` What have I done to make you unable to trust me? ``` @@ -545,7 +467,7 @@ Should feel adult, consent-based, respectful, optional, and never pushy. Use: -```text +``` What kind of affection helps you feel wanted without feeling pressured? What helps you feel comfortable talking about desire with me? What is one way I can make physical closeness feel safer and more relaxed? @@ -553,7 +475,7 @@ What is one way I can make physical closeness feel safer and more relaxed? Avoid: -```text +``` What should I do to make sure you give me more sex? What fantasy do you have to tell me tonight? Why do you not want me more? @@ -561,19 +483,17 @@ Why do you not want me more? Sensitive packs should include: -```bat -ECHO Consent-first wording. -ECHO No pressure. -ECHO No shame. -ECHO No assumptions about gender roles. -ECHO No assumptions about sex drive. -ECHO No coercive language. -ECHO No questions that pressure disclosure of trauma. -``` +- Consent-first wording. +- No pressure. +- No shame. +- No assumptions about gender roles. +- No assumptions about sex drive. +- No coercive language. +- No questions that pressure disclosure of trauma. --- -# Sex / Identity Targeting Rule +# 9. Sex / Identity Targeting Rule Some Closer packs are general relationship packs. Some packs, especially Desire Sync and sexual preference packs, may need identity-aware filtering. @@ -581,19 +501,13 @@ Use the `sex` field carefully. ## Default Rule -Use: - -```json -"sex": "neutral" -``` - -when the question can apply naturally to any adult partner. +Use `"sex": "neutral"` when the question can apply naturally to any adult partner. Most questions should be neutral when the same wording works for everyone. Good neutral examples: -```text +``` What kind of kiss makes you forget what you were saying? What kind of flirting gets your attention fastest? What helps you feel comfortable saying what you want? @@ -602,19 +516,7 @@ What kind of touch makes you melt the quickest? ## When to Use Female or Male -Use: - -```json -"sex": "female" -``` - -or: - -```json -"sex": "male" -``` - -only when the app intentionally filters questions by the user's selected identity and the question is truly written for that identity or body context. +Use `"sex": "female"` or `"sex": "male"` only when the app intentionally filters questions by the user's selected identity and the question is truly written for that identity or body context. Do not mark a question female or male just because the pack is sexual. A lot of sexual preference questions can stay neutral. @@ -624,7 +526,7 @@ Do not create female/male duplicates unless the wording, answer options, or body Bad: -```text +``` Female: What kind of kiss turns you on? Male: What kind of kiss turns you on? ``` @@ -633,7 +535,7 @@ That should be one neutral question. Better: -```text +``` Neutral: What kind of kiss makes you want more? ``` @@ -653,14 +555,14 @@ Do not assume: Bad: -```text +``` Male: How often do you need sex to feel loved? Female: How can your partner make you feel safe enough to want sex? ``` Better: -```text +``` Neutral: What helps you feel wanted without feeling pressured? Neutral: What helps you move from daily stress into desire? ``` @@ -671,7 +573,7 @@ Even if the app currently asks users to identify as male or female, question wor Do not assume every couple is male/female. -Do not assume one answer belongs to “the woman” and another belongs to “the man.” +Do not assume one answer belongs to "the woman" and another belongs to "the man." If a question can work for any couple, keep it neutral. @@ -679,11 +581,9 @@ If a question can work for any couple, keep it neutral. For `sexual_preferences.json`, use this as the default content mix unless the app logic requires something different: -```text -70–80% neutral -10–15% female-targeted -10–15% male-targeted -``` +- 70-80% neutral +- 10-15% female-targeted +- 10-15% male-targeted The neutral questions should carry most of the pack because they work across more couples. @@ -711,11 +611,9 @@ Claude must not create female/male questions unless the app filtering logic supp Allowed `sex` values: -```text -neutral -female -male -``` +- neutral +- female +- male Do not invent new values unless the app schema is updated first. @@ -731,16 +629,14 @@ Closer is not therapy, counseling, crisis support, or medical advice. Questions must not: -```bat -ECHO Encourage staying in unsafe relationships. -ECHO Pressure forgiveness. -ECHO Minimize abuse. -ECHO Encourage sexual pressure. -ECHO Ask users to disclose trauma before they are ready. -ECHO Diagnose a partner. -ECHO Tell a partner what they owe. -ECHO Encourage monitoring, control, or isolation. -``` +- Encourage staying in unsafe relationships. +- Pressure forgiveness. +- Minimize abuse. +- Encourage sexual pressure. +- Ask users to disclose trauma before they are ready. +- Diagnose a partner. +- Tell a partner what they owe. +- Encourage monitoring, control, or isolation. ## Abuse-sensitive rule @@ -748,13 +644,13 @@ Avoid questions that frame controlling behavior as a normal boundary. Bad: -```text +``` What rule should we have about who your partner can talk to? ``` Better: -```text +``` What helps you feel secure in our relationship while still respecting each other's independence? ``` @@ -762,13 +658,13 @@ What helps you feel secure in our relationship while still respecting each other Bad: -```text +``` How can I get you to be more physically affectionate? ``` Better: -```text +``` What kind of affection feels good to you when you are open to closeness? ``` @@ -786,13 +682,13 @@ Long questions are okay only when the topic needs softness or context. Bad: -```text +``` What boundary do you need around family, money, friends, work, and rest so you feel loved and respected? ``` Better: -```text +``` What family boundary would make our relationship feel more protected? ``` @@ -800,27 +696,27 @@ What family boundary would make our relationship feel more protected? Bad: -```text +``` What would help you feel safe, seen, valued, loved, respected, and emotionally connected? ``` Better: -```text +``` What helps you feel respected by me? ``` -## Avoid vague “more” questions +## Avoid vague "more" questions Bad: -```text +``` How can we be more connected? ``` Better: -```text +``` What is one thing we could do tonight to feel closer? ``` @@ -828,251 +724,38 @@ What is one thing we could do tonight to feel closer? Bad: -```text +``` What do I do that makes date night feel bad? ``` Better: -```text +``` What tends to make date night harder for you to enjoy? ``` --- -# 12. JSON Quality Rules - -Every JSON file should pass these checks. - -```bat -ECHO [ ] Valid JSON. -ECHO [ ] Category id matches file purpose. -ECHO [ ] Category title sounds user-facing. -ECHO [ ] Category access matches actual free/premium strategy. -ECHO [ ] Metadata counts match actual question counts. -ECHO [ ] All question IDs are unique. -ECHO [ ] All question texts are unique. -ECHO [ ] No near-duplicate blocks. -ECHO [ ] Type counts match metadata. -ECHO [ ] Free/premium counts match metadata. -ECHO [ ] Depth values are valid. -ECHO [ ] Access values are valid. -ECHO [ ] Options have unique IDs inside each question. -ECHO [ ] Option IDs are neutral and clean. -ECHO [ ] Scale labels are present when needed. -ECHO [ ] No malformed keys like m a x _ l e n g t h. -ECHO [ ] No placeholder text. -ECHO [ ] No accidental old gendered IDs unless intentionally used. -``` - -Recommended access values: - -```text -free -premium -``` - -Recommended category access values: - -```text -free -premium -mixed -``` - -Recommended depth values: - -```text -light -medium -deep -``` - -Recommended question types: - -```text -written -single_choice -multi_choice -scale -this_or_that -``` - ---- - -# 13. Pack Structure Recommendation - -For a 250-question pack: - -```bat -SET TOTAL_QUESTIONS=250 -SET FREE_QUESTIONS=75 -SET PREMIUM_QUESTIONS=175 -SET WRITTEN=150 -SET SINGLE_CHOICE=40 -SET MULTI_CHOICE=20 -SET SCALE=25 -SET THIS_OR_THAT=15 -``` - -This structure is acceptable if the current app expects those counts. - -But quality matters more than exact counts. If a pack cannot support 250 good questions without filler, reduce the pack or split it. - ---- - -# 14. Content Batching Process - -Do not write all 250 questions in one creative pass. - -Use this process: - -```bat -ECHO Step 1: Define pack purpose. -ECHO Step 2: Define subtopics. -ECHO Step 3: Write 40-50 high-quality questions. -ECHO Step 4: Review tone and repetition. -ECHO Step 5: Write the next batch. -ECHO Step 6: Add choice, scale, and this-or-that questions. -ECHO Step 7: Assign free/premium. -ECHO Step 8: Assign depth. -ECHO Step 9: Validate JSON. -ECHO Step 10: Read the full file like a user. -``` - ---- - -# 15. Subtopic Planning - -Each pack should have subtopics to prevent repetition. - -Example for Date Night: - -```text -easy dates -low-cost dates -at-home dates -going out -planning preferences -romance style -fun and play -food and drinks -music and movies -seasonal dates -surprises -feeling wanted -getting out of a rut -after-kids / busy life -date-night stress -memories -future date dreams -``` - -Example for Boundaries: - -```text -alone time -phone privacy -social media -family involvement -friendships -money -work time -rest -chores -home space -conflict -tone of voice -physical affection -private conversations -parenting/family roles -emotional bandwidth -plans and scheduling -personal belongings -sleep -stress -``` - ---- - -# 16. Repetition Check - -A pack fails if it has blocks like this: - -```text -What boundary around alone time would help you feel respected? -What boundary around phone privacy would help you feel respected? -What boundary around family involvement would help you feel respected? -What boundary around friendships would help you feel respected? -``` - -Instead, each question should have its own angle. - -Better: - -```text -When you need alone time, how should I respond so it does not feel personal? -What phone privacy boundary would help us feel trusted instead of watched? -How involved should family be in decisions that affect just the two of us? -What helps friendships feel healthy without making our relationship feel pushed aside? -``` - ---- - -# 17. Human Read-Aloud Test +# 12. Human Read-Aloud Test Before finalizing, read 25 random questions out loud. Reject questions that: -```bat -ECHO Sound stiff. -ECHO Sound embarrassing for the wrong reason. -ECHO Sound like a therapy script. -ECHO Sound too much like another question. -ECHO Take too long to understand. -ECHO Would make a normal couple roll their eyes. -``` +- Sound stiff. +- Sound embarrassing for the wrong reason. +- Sound like a therapy script. +- Sound too much like another question. +- Take too long to understand. +- Would make a normal couple roll their eyes. --- -# 18. Claude Instructions for Rewriting JSON Packs - -When Claude rewrites a pack: - -```bat -ECHO Read the existing JSON first. -ECHO Preserve required schema unless told otherwise. -ECHO Preserve required counts unless told otherwise. -ECHO Improve wording, variety, and product feel. -ECHO Do not create repetitive template blocks. -ECHO Do not use weird phrasing. -ECHO Do not overuse therapy language. -ECHO Do not make sensitive prompts coercive. -ECHO Validate the final JSON. -ECHO Report count totals. -ECHO Report any schema changes. -``` - -Claude should not say a file is done unless: - -```bat -ECHO The JSON parses. -ECHO The counts match. -ECHO IDs are unique. -ECHO Question texts are unique. -ECHO Free/premium counts match. -ECHO Type counts match. -ECHO The tone guide was followed. -``` - ---- - -# 19. Good Question Examples by Category +# 13. Good Question Examples by Category ## Date Night -```text +``` What is a date we could plan this month that would feel easy but special? What makes you feel like I really wanted time with you? What kind of date helps you relax the fastest? @@ -1082,7 +765,7 @@ What would make a regular night feel romantic? ## Boundaries -```text +``` When you need space, what helps you feel understood instead of distant? What is one small boundary that would make our home feel calmer? What topic do you wish we handled more gently? @@ -1092,7 +775,7 @@ What is one way we can protect our time together from outside stress? ## Communication -```text +``` What helps you open up when something is bothering you? When do you feel easiest to talk to me? What is one thing I could say more often? @@ -1102,7 +785,7 @@ What helps you know I am really listening? ## Fun -```text +``` What is something silly we should do together soon? What little adventure would make this week better? What is an inside joke of ours that you still love? @@ -1112,7 +795,7 @@ What is something we should try just because it sounds fun? ## Trust -```text +``` What small action helps you trust me more? What makes an apology feel real to you? What helps you feel reassured without having to ask twice? @@ -1122,7 +805,7 @@ What helps us feel like we are on the same team? ## Physical Intimacy -```text +``` What kind of affection helps you feel closest to me? When do you feel most comfortable being physically close? What helps touch feel relaxed instead of expected? @@ -1132,159 +815,18 @@ What makes cuddling or closeness feel safe and easy? --- -# 20. Final Standard +# 14. Final Standard A finished Closer question pack should feel: -```text -Human. -Warm. -Private. -Clear. -Useful. -Specific. -Enjoyable. -Respectful. -Worth paying for. -``` +- Human. +- Warm. +- Private. +- Clear. +- Useful. +- Specific. +- Enjoyable. +- Respectful. +- Worth paying for. If a question does not help a couple feel closer, understand each other, laugh together, plan something, repair something, or feel safer with each other, it probably does not belong in Closer. - - ---- - -# 4. Fun-First Rule - -Most Closer questions should feel enjoyable to answer. - -That does not mean every question has to be silly, flirty, or light. Some packs cover serious topics like boundaries, trust, money, conflict, sex, and repair. But even serious packs should not feel like homework, interrogation, therapy intake forms, or emotional labor. - -The user should usually feel one or more of these after answering: - -```text -Interested -Amused -Comforted -Wanted -Understood -Curious -Relieved -Closer -``` - -A Closer question should avoid making users feel: - -```text -Accused -Tested -Pressured -Drained -Embarrassed in a bad way -Like they are doing therapy homework -Like they are about to start a fight -``` - -## Fun-First Balance by Pack Type - -Use this as the default balance unless the pack has a special reason to be different. - -| Pack type | Light / playful / easy | Meaningful / practical | Deeper | -|---|---:|---:|---:| -| Fun, Date Night, Home Life | 60–70% | 20–30% | 10% | -| Boundaries, Trust, Conflict | 30–40% | 40–50% | 10–20% | -| Sex, Desire, Physical Intimacy | 40–50% | 30–40% | 10–20% | -| Money, Future, Values | 35–45% | 40–50% | 10–15% | - -## Fun Does Not Mean Shallow - -A fun question can still reveal something real. - -Weak: - -```text -What is your favorite color? -``` - -Better: - -```text -What color would you pick for a room that felt like us? -``` - -Weak: - -```text -What food do you like? -``` - -Better: - -```text -What meal would instantly make a night together feel better? -``` - -Weak: - -```text -What date sounds fun? -``` - -Better: - -```text -What is a low-effort date that would still make you excited to see me? -``` - -## Serious Does Not Mean Heavy - -Even serious topics should be written in a way that feels safe and answerable. - -Too heavy: - -```text -What unresolved emotional wound affects our relationship dynamic? -``` - -Better: - -```text -What is one thing we could handle more gently with each other? -``` - -Too confrontational: - -```text -What do I do that makes you not trust me? -``` - -Better: - -```text -What small action helps you feel more secure with me? -``` - -Too clinical: - -```text -What communication structure would support healthier conflict resolution? -``` - -Better: - -```text -When we disagree, what helps us slow down before it turns into a fight? -``` - -## Fun-First Review Questions - -Before finalizing a pack, ask: - -- Would this pack feel enjoyable to open after a long day? -- Are there enough easy questions to keep users from feeling drained? -- Would a couple want to compare answers? -- Does the pack include curiosity, play, warmth, or sweetness? -- Are the deeper questions spaced out enough? -- Does the pack still feel like Closer, not therapy homework? - -If a pack feels too heavy, add more light, playful, practical, or curiosity-based questions. - diff --git a/seed/questions/QUESTION_REWRITE_PLAN.md b/seed/questions/QUESTION_REWRITE_PLAN.md new file mode 100644 index 00000000..41246d1d --- /dev/null +++ b/seed/questions/QUESTION_REWRITE_PLAN.md @@ -0,0 +1,139 @@ +# Closer Question Pack Rewrite Plan + +## Purpose + +This document defines the active rewrite plan: what needs to happen, in what order, and how to validate each pack. + +For writing philosophy and tone, see `QUESTION_CONTENT_GUIDE.md`. +For JSON schema and validation rules, see `QUESTION_SCHEMA.md`. + +--- + +# 1. Product Goal + +Closer is a relationship app, not a survey or therapy worksheet. + +Every question should make couples smile, laugh, learn something new, remember something, plan something together, or have a meaningful conversation. + +The app should feel like a game you accidentally spend an hour playing. + +If a question feels like homework, rewrite it. + +--- + +# 2. Consumer First Philosophy + +People are opening Closer while sitting on the couch, riding in the car, eating dinner, or lying in bed. + +They are not looking to complete an emotional worksheet. + +Questions should be quick, conversational, and rewarding. + +A couple should naturally answer dozens of questions in one session. + +Every category should create moments like: + +- "I didn't know that." +- "Really?" +- "That's adorable." +- "We should do that." +- laughter +- flirting +- nostalgia +- future plans + +--- + +# 3. Emotional Mix + +Every pack should roughly contain: + +- 35% fun and playful +- 25% everyday relationship +- 20% meaningful conversations +- 10% future dreams and planning +- 10% deeper vulnerability + +Never group heavy questions together. + +Every category must contain moments of humor and curiosity. + +--- + +# 4. Rewrite Rules + +For every category: + +- Rewrite every question from scratch. +- Follow the content guide. +- Keep category ids. +- Use conversational language. +- Avoid therapy language. +- Avoid corporate wording. +- Avoid repetitive templates. +- Keep answers short. +- Use 4 to 6 options for choice questions. +- Make multi_choice clearly allow multiple answers. +- Make scale neutral. +- Keep written questions rare. + +--- + +# 5. Fun Injection + +Every category must include: + +- at least 10 playful questions +- at least 5 questions that create laughter +- at least 5 questions that inspire a future date, memory, or shared activity + +Even serious categories should contain lighter moments. + +--- + +# 6. Rewrite Order + +1. fun +2. date_night +3. quality_time +4. communication +5. gratitude +6. future +7. home_life +8. values +9. stress +10. money +11. boundaries +12. conflict +13. conflict_repair +14. trust +15. rebuilding_trust +16. difficult_conversations +17. emotional_intimacy +18. physical_intimacy +19. couple_intimacy +20. sex_and_desire +21. sexual_preferences + +--- + +# 7. Validation + +Every rewritten pack must pass: + +- Valid JSON +- 250 questions +- 75 free +- 175 premium +- 140 multi_choice +- 50 choice +- 35 scale +- 15 either_or +- 10 written +- Valid depth values only +- No duplicate ids +- No duplicate questions +- No malformed keys +- No placeholder text +- No therapy worksheet tone +- Every category contains fun, curiosity, and meaningful conversations diff --git a/seed/questions/QUESTION_SCHEMA.md b/seed/questions/QUESTION_SCHEMA.md new file mode 100644 index 00000000..4bcc75a5 --- /dev/null +++ b/seed/questions/QUESTION_SCHEMA.md @@ -0,0 +1,425 @@ +# Closer Question Schema + +## Purpose + +This document defines the JSON schema, question types, validation rules, and required counts for Closer question packs. + +For writing philosophy and tone, see `QUESTION_CONTENT_GUIDE.md`. +For the active rewrite checklist and category order, see `QUESTION_REWRITE_PLAN.md`. + +--- + +# 1. Question Types + +## multi_choice + +Select every option that applies. + +Primary question type. At least 75% of all questions must be choice-based (multi_choice + choice). + +```json +{ + "type": "multi_choice", + "text": "What helps you feel relaxed on a date with me?", + "options": [ + { "id": "no_rushing", "text": "Not feeling rushed" }, + { "id": "phones_away", "text": "Putting phones away" }, + { "id": "good_food", "text": "Good food" }, + { "id": "easy_conversation", "text": "Easy conversation" }, + { "id": "physical_affection", "text": "Physical affection" }, + { "id": "clear_plan", "text": "Having a plan" } + ] +} +``` + +Rules: + +- Prompt should clearly allow multiple answers. +- Options should not shame either partner. +- Include practical and emotional options when possible. + +## choice + +Pick the single best answer. + +```json +{ + "type": "choice", + "text": "Which kind of date sounds best this week?", + "options": [ + { "id": "cozy_at_home", "text": "Cozy at home" }, + { "id": "dinner_out", "text": "Dinner out" }, + { "id": "something_playful", "text": "Something playful" }, + { "id": "something_outside", "text": "Something outside" }, + { "id": "surprise_me", "text": "Surprise me" } + ] +} +``` + +Rules: + +- Options should be short. +- Options should not overlap too much. +- Options should sound like real choices. +- Use 4 to 6 options. + +## scale + +Rate agreement, comfort, importance, confidence, or frequency. + +```json +{ + "type": "scale", + "text": "How much do you feel like we need a real date soon?", + "scale": { + "min": 1, + "max": 5, + "min_label": "Not much", + "max_label": "Very much" + } +} +``` + +Rules: + +- Scale labels should be gentle and neutral. +- Do not make the low end sound bad or shameful. +- Scale questions should measure one thing only. + +Bad: + +``` +How badly are we failing at making time for each other? +``` + +Better: + +``` +How much would some intentional time together help us right now? +``` + +## either_or + +Very fast playful questions. Should take under three seconds. + +```json +{ + "type": "either_or", + "text": "Planned date or spontaneous date?" +} +``` + +Rules: + +- Prompts should be quick. +- Avoid choices that imply one partner is wrong. +- Best used in fun, date, intimacy, home, and lifestyle packs. + +## written + +Reserved for questions where a short written response adds meaningful value. + +Never use written questions for basic preferences. + +```json +{ + "type": "written", + "text": "What is one small thing I do that makes you feel cared for?" +} +``` + +Good written examples: + +``` +What is one small thing I do that makes you feel cared for? +What is a memory of us that still makes you smile? +What is something you wish we made more time for? +``` + +Avoid written questions that are too vague: + +``` +How can we deepen our connection? +``` + +Better: + +``` +What is one thing we could do this week that would make us feel more like a team? +``` + +--- + +# 2. Required Counts + +Every 250-question pack must contain: + +| Type | Count | Percent | +|---|---|---| +| multi_choice | 140 | 56% | +| choice | 50 | 20% | +| scale | 35 | 14% | +| either_or | 15 | 6% | +| written | 10 | 4% | + +At least 75% of all questions must be choice-based (multi_choice + choice). + +Written questions should be rare and only used when typing creates a better conversation. + +## Free vs Premium + +| Access | Count | +|---|---| +| free | 75 | +| premium | 175 | + +## Depth + +Valid depth values: + +- light +- medium +- deep + +## Access + +Valid access values: + +- free +- premium + +## Category Access + +Valid category access values: + +- free +- premium +- mixed + +--- + +# 3. JSON Structure + +## Category metadata + +```json +{ + "id": "date_night", + "title": "Date Night", + "access": "mixed", + "description": "Plan, enjoy, and remember time together.", + "count": 250, + "free_count": 75, + "premium_count": 175, + "questions": [] +} +``` + +## Question object + +```json +{ + "id": "dn_001", + "type": "multi_choice", + "text": "What helps you feel relaxed on a date with me?", + "depth": "medium", + "access": "free", + "sex": "neutral", + "options": [ + { "id": "no_rushing", "text": "Not feeling rushed" }, + { "id": "phones_away", "text": "Putting phones away" }, + { "id": "good_food", "text": "Good food" }, + { "id": "easy_conversation", "text": "Easy conversation" }, + { "id": "physical_affection", "text": "Physical affection" }, + { "id": "clear_plan", "text": "Having a plan" } + ] +} +``` + +## Scale question object + +```json +{ + "id": "dn_042", + "type": "scale", + "text": "How much do you feel like we need a real date soon?", + "depth": "medium", + "access": "free", + "sex": "neutral", + "scale": { + "min": 1, + "max": 5, + "min_label": "Not much", + "max_label": "Very much" + } +} +``` + +## Either/or question object + +```json +{ + "id": "dn_089", + "type": "either_or", + "text": "Planned date or spontaneous date?", + "depth": "light", + "access": "free", + "sex": "neutral" +} +``` + +## Written question object + +```json +{ + "id": "dn_113", + "type": "written", + "text": "What is one date we should bring back?", + "depth": "medium", + "access": "premium", + "sex": "neutral" +} +``` + +--- + +# 4. Validation Rules + +Every rewritten pack must pass: + +- Valid JSON +- 250 questions +- 75 free +- 175 premium +- 140 multi_choice +- 50 choice +- 35 scale +- 15 either_or +- 10 written +- Valid depth values only (light, medium, deep) +- Valid access values only (free, premium) +- Valid type values only (multi_choice, choice, scale, either_or, written) +- Valid sex values only (neutral, female, male) +- No duplicate question IDs +- No duplicate question texts +- No near-duplicate blocks +- No malformed keys +- No placeholder text +- No therapy worksheet tone +- Options have unique IDs inside each question +- Option IDs are neutral and clean +- Scale labels are present when needed +- Every category contains fun, curiosity, and meaningful conversations + +## JSON Quality Checklist + +- [ ] Valid JSON. +- [ ] Category id matches file purpose. +- [ ] Category title sounds user-facing. +- [ ] Category access matches actual free/premium strategy. +- [ ] Metadata counts match actual question counts. +- [ ] All question IDs are unique. +- [ ] All question texts are unique. +- [ ] No near-duplicate blocks. +- [ ] Type counts match metadata. +- [ ] Free/premium counts match metadata. +- [ ] Depth values are valid. +- [ ] Access values are valid. +- [ ] Options have unique IDs inside each question. +- [ ] Option IDs are neutral and clean. +- [ ] Scale labels are present when needed. +- [ ] No malformed keys like m a x _ l e n g t h. +- [ ] No placeholder text. +- [ ] No accidental old gendered IDs unless intentionally used. + +--- + +# 5. Subtopic Planning + +Each pack should have subtopics to prevent repetition. + +Example for Date Night: + +- easy dates +- low-cost dates +- at-home dates +- going out +- planning preferences +- romance style +- fun and play +- food and drinks +- music and movies +- seasonal dates +- surprises +- feeling wanted +- getting out of a rut +- after-kids / busy life +- date-night stress +- memories +- future date dreams + +Example for Boundaries: + +- alone time +- phone privacy +- social media +- family involvement +- friendships +- money +- work time +- rest +- chores +- home space +- conflict +- tone of voice +- physical affection +- private conversations +- parenting/family roles +- emotional bandwidth +- plans and scheduling +- personal belongings +- sleep +- stress + +--- + +# 6. Repetition Check + +A pack fails if it has blocks like this: + +``` +What boundary around alone time would help you feel respected? +What boundary around phone privacy would help you feel respected? +What boundary around family involvement would help you feel respected? +What boundary around friendships would help you feel respected? +``` + +Instead, each question should have its own angle. + +Better: + +``` +When you need alone time, how should I respond so it does not feel personal? +What phone privacy boundary would help us feel trusted instead of watched? +How involved should family be in decisions that affect just the two of us? +What helps friendships feel healthy without making our relationship feel pushed aside? +``` + +--- + +# 7. Content Batching Process + +Do not write all 250 questions in one creative pass. + +Use this process: + +1. Define pack purpose. +2. Define subtopics. +3. Write 40-50 high-quality questions. +4. Review tone and repetition. +5. Write the next batch. +6. Add choice, scale, and this-or-that questions. +7. Assign free/premium. +8. Assign depth. +9. Validate JSON. +10. Read the full file like a user.