diff --git a/seed/questions/QUESTION_CONTENT_GUIDE.md b/seed/questions/QUESTION_CONTENT_GUIDE.md index 21e755b7..575cc6a4 100644 --- a/seed/questions/QUESTION_CONTENT_GUIDE.md +++ b/seed/questions/QUESTION_CONTENT_GUIDE.md @@ -4,7 +4,7 @@ This guide defines how Closer question packs should be written, reviewed, and validated. -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, overly sexual, or like therapy homework. +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. @@ -14,30 +14,30 @@ Use this guide before writing or rewriting any question JSON file. Closer should sound: -- Warm -- Private -- Plainspoken -- Emotionally honest -- Lightly playful when appropriate -- Easy to answer -- Respectful of both partners -- Safe and non-pressuring +- warm +- private +- plainspoken +- emotionally honest +- lightly playful when appropriate +- easy to answer +- respectful of both partners +- safe and non-pressuring Closer should not sound: -- Robotic -- Overly formal -- Fake-deep -- Preachy -- Judgmental -- Clinical -- Like a therapist worksheet -- Like a corporate wellness app -- Sexually pushy -- Repetitive -- Awkwardly generated +- robotic +- overly formal +- fake-deep +- preachy +- judgmental +- clinical +- like a therapist worksheet +- like a corporate wellness app +- sexually pushy +- repetitive +- awkwardly generated -## Voice Rule +## Voice rule A good Closer question should sound like something a real person could comfortably ask their partner. @@ -65,12 +65,14 @@ What is one money habit we could agree on that would make things feel calmer bet Every question should pass this test: -- 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? +```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? +``` If the answer is no, rewrite it. @@ -103,38 +105,30 @@ This makes me feel accused. --- -# 4. Pack Purpose +# 4. Category Purpose -Every pack needs a clear job. +Every pack needs a clear purpose. Before writing a pack, define: -- Pack name -- Pack purpose -- How the user should feel while answering -- What kind of connection the pack should create -- What free users should get from the pack -- What premium users should get from the pack +```bat +SET PACK_NAME= +SET PACK_PURPOSE= +SET USER_FEELING= +SET RELATIONSHIP_OUTCOME= +SET FREE_VALUE= +SET PREMIUM_VALUE= +``` Example: -```md -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. +```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. ``` --- @@ -179,12 +173,14 @@ What kind of attention from me makes you feel closest? What do you miss about the way we used to spend time together? ``` -## Depth Rules +## Depth rules -- 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. +```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. +``` --- @@ -194,9 +190,9 @@ Each question type should have a purpose. ## written -Use written questions for stories, memories, reflection, emotional honesty, and open-ended answers. +Use for stories, memories, reflection, emotional honesty, and open-ended answers. -Good examples: +Good written examples: ```text What is one small thing I do that makes you feel cared for? @@ -220,9 +216,9 @@ What is one thing we could do this week that would make us feel more like a team ## single_choice -Use single-choice questions for preferences and simple decisions. +Use for preferences and simple decisions. -Good example: +Good single-choice example: ```json { @@ -240,19 +236,20 @@ Good example: Rules: -- Options should be short. -- Options should not overlap too much. -- Options should sound like real choices. -- Avoid more than 6 options unless truly needed. -- Option IDs should be clean, neutral, and stable. +```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 multi-choice questions when more than one answer can be true. +Use when more than one answer can be true. -Good example: +Good multi-choice example: ```json { @@ -271,18 +268,19 @@ Good example: Rules: -- Multi-choice prompts should say or imply that multiple answers are okay. -- Options should not shame either partner. -- Include practical and emotional options when possible. -- Avoid options that are almost the same thing. +```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 scale questions for comfort level, closeness, energy, readiness, satisfaction, or frequency. +Use for comfort level, closeness, energy, readiness, satisfaction, or frequency. -Good example: +Good scale example: ```json { @@ -299,10 +297,11 @@ Good example: 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. -- Avoid loaded or accusatory wording. +```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: @@ -320,9 +319,9 @@ How much would some intentional time together help us right now? ## this_or_that -Use this-or-that questions for fast, playful, low-pressure choices. +Use for fast, playful, low-pressure choices. -Good examples: +Good this-or-that examples: ```text Planned date or spontaneous date? @@ -333,10 +332,11 @@ Sunset walk or late-night drive? Rules: -- This-or-that prompts should be quick. -- Avoid choices that imply one partner is wrong. -- Use this type most often in fun, date, intimacy, home, and lifestyle packs. -- Do not overuse it in serious conflict or trust packs. +```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. +``` --- @@ -346,23 +346,25 @@ 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 +## Free questions should be: -- Easy to answer -- Warm and useful -- Good enough to create trust -- Low-pressure -- Representative of the pack -- Strong enough that the app feels valuable before payment +```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 +## Premium questions should be: -- More specific -- More thoughtful -- More emotionally useful -- More creative -- More likely to start a meaningful conversation -- Worth paying for +```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.” @@ -382,9 +384,9 @@ Premium: What kind of date would make you feel pursued, not just scheduled? --- -# 8. Phrases to Avoid +# 8. Banned or Overused Phrases -Avoid these unless there is a very good reason: +Avoid these unless there is a very good reason. ```text What boundary around... @@ -405,7 +407,7 @@ navigate conflict honor your needs ``` -These phrases are not always wrong, but they quickly make the app sound generic, clinical, or AI-written. +These phrases are not always wrong, but they quickly make the app sound generic or clinical. Use natural language instead. @@ -437,9 +439,9 @@ What is one small thing that makes you want to be closer to me? # 9. Tone Rules by Pack Type -## Fun Packs +## Fun packs -Fun packs should feel light, playful, and easy. +Should feel light, playful, and easy. Use: @@ -457,9 +459,9 @@ How can we optimize shared leisure experiences? --- -## Date Night Packs +## Date Night packs -Date Night packs should feel romantic, playful, practical, and low-pressure. +Should feel romantic, playful, practical, and low-pressure. Use: @@ -477,9 +479,9 @@ What date structure would best support our connection goals? --- -## Boundaries Packs +## Boundaries packs -Boundaries packs should feel respectful, calm, and non-accusing. +Should feel respectful, calm, and non-accusing. Use: @@ -497,9 +499,9 @@ What boundary around boundaries would support emotional safety? --- -## Conflict Packs +## Conflict packs -Conflict packs should feel safe, repair-focused, and not blaming. +Should feel safe, repair-focused, and not blaming. Use: @@ -517,9 +519,9 @@ What do I always do wrong during conflict? --- -## Trust Packs +## Trust packs -Trust packs should feel careful, honest, and non-punishing. +Should feel careful, honest, and non-punishing. Use: @@ -537,9 +539,9 @@ What have I done to make you unable to trust me? --- -## Sex, Desire, and Physical Intimacy Packs +## Sex, desire, and physical intimacy packs -Sex, desire, and physical intimacy packs should feel adult, consent-based, respectful, optional, and never pushy. +Should feel adult, consent-based, respectful, optional, and never pushy. Use: @@ -559,13 +561,15 @@ Why do you not want me more? Sensitive packs should include: -- 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 +```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. +``` --- @@ -575,17 +579,18 @@ Closer is not therapy, counseling, crisis support, or medical advice. Questions must not: -- 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 -- Frame controlling behavior as love or boundaries +```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. +``` -## Abuse-Sensitive Rule +## Abuse-sensitive rule Avoid questions that frame controlling behavior as a normal boundary. @@ -601,7 +606,7 @@ Better: What helps you feel secure in our relationship while still respecting each other's independence? ``` -## Consent Rule +## Consent rule Bad: @@ -619,13 +624,13 @@ What kind of affection feels good to you when you are open to closeness? # 11. Wording Rules -## Keep Questions Short +## Keep questions short Aim for 8 to 22 words when possible. -Longer questions are okay only when the topic needs softness or context. +Long questions are okay only when the topic needs softness or context. -## Ask One Thing at a Time +## Ask one thing at a time Bad: @@ -639,7 +644,7 @@ Better: What family boundary would make our relationship feel more protected? ``` -## Avoid Stacked Emotional Words +## Avoid stacked emotional words Bad: @@ -653,7 +658,7 @@ Better: What helps you feel respected by me? ``` -## Avoid Vague “More” Questions +## Avoid vague “more” questions Bad: @@ -667,7 +672,7 @@ Better: What is one thing we could do tonight to feel closer? ``` -## Avoid Blame +## Avoid blame Bad: @@ -685,26 +690,28 @@ What tends to make date night harder for you to enjoy? # 12. JSON Quality Rules -Every JSON file should pass these checks: +Every JSON file should pass these checks. -- 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 +```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: @@ -745,20 +752,20 @@ this_or_that For a 250-question pack: -```text -Total questions: 250 -Free questions: 75 -Premium questions: 175 -Written: 150 -Single choice: 40 -Multi choice: 20 -Scale: 25 -This-or-that: 15 +```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. -Quality matters more than exact counts. If a pack cannot support 250 good questions without filler, reduce the pack or split it. +But quality matters more than exact counts. If a pack cannot support 250 good questions without filler, reduce the pack or split it. --- @@ -768,16 +775,18 @@ Do not write all 250 questions in one creative pass. Use this process: -1. Define the pack purpose. -2. Define subtopics. -3. Write 40 to 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. +```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. +``` --- @@ -785,7 +794,7 @@ Use this process: Each pack should have subtopics to prevent repetition. -## Example: Date Night +Example for Date Night: ```text easy dates @@ -801,13 +810,13 @@ seasonal dates surprises feeling wanted getting out of a rut -busy-life dates +after-kids / busy life date-night stress memories future date dreams ``` -## Example: Boundaries +Example for Boundaries: ```text alone time @@ -824,7 +833,7 @@ conflict tone of voice physical affection private conversations -parenting or family roles +parenting/family roles emotional bandwidth plans and scheduling personal belongings @@ -864,12 +873,14 @@ Before finalizing, read 25 random questions out loud. Reject questions that: -- 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 +```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. +``` --- @@ -877,28 +888,31 @@ Reject questions that: When Claude rewrites a pack: -1. Read this guide first. -2. Read the existing JSON file. -3. Preserve the required schema unless told otherwise. -4. Preserve required counts unless told otherwise. -5. Improve wording, variety, and product feel. -6. Do not create repetitive template blocks. -7. Do not use weird phrasing. -8. Do not overuse therapy language. -9. Do not make sensitive prompts coercive. -10. Validate the final JSON. -11. Report count totals. -12. Report any schema changes. +```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: -- The JSON parses. -- The counts match. -- IDs are unique. -- Question texts are unique. -- Free/premium counts match. -- Type counts match. -- The tone guide was followed. +```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. +``` --- @@ -977,8 +991,148 @@ 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. +