Closer/seed/questions/QUESTION_SCHEMA.md

Closer Question Schema

See also: QUESTION_CONTENT_GUIDE.md | QUESTION_REWRITE_PLAN.md | QUESTION_QUALITY_CHECKLIST.md

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 rewrite workflow and special pack exceptions, see QUESTION_REWRITE_PLAN.md.

1. Question Types

multi_choice

Select every option that applies.

Primary question type. At least 75 percent of standard pack questions must be choice based when combined with single_choice.

{
  "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.
• Use 4 to 6 options.

single_choice

Select one best answer.

{
  "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:

• Options should be short.
• Options should not overlap too much.
• Options should sound like real choices.
• Every option must directly answer the prompt.
• Use 4 to 6 options.

scale

Rate agreement, comfort, importance, confidence, or frequency.

{
  "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?

this_or_that

Very fast playful questions.

Should take under three seconds.

{
  "type": "this_or_that",
  "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.

{
  "type": "written",
  "text": "What is one small thing I do that makes you feel cared for?",
  "answer": {
    "max_length": 500
  }
}

Written questions require an answer configuration with max_length.

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

Standard 250 Question Packs

Every standard 250 question pack must contain:

Type	Count	Percent
multi_choice	140	56%
single_choice	50	20%
scale	35	14%
this_or_that	15	6%
written	10	4%

At least 75 percent of all standard pack questions must be choice based.

Written questions should be rare and only used when typing creates a better conversation.

Special Packs

Special product packs may override standard counts only when documented.

The daily single choice weekday pack is a special pack.

It may use all single_choice questions when the pack metadata and rewrite plan say so.

Current daily pack target counts:

Field	Count
total	500
free	75
premium	425
single_choice	500

These counts do not apply to standard category packs. Standard packs still use the normal 250 question mix.

Free vs Premium

Standard 250 question packs:

Access	Count
free	75
premium	175

Special packs must define their own free and premium counts in metadata.

Depth

Valid depth values in the documented schema:

• light
• medium
• deep

Do not use numeric depth values unless the active app import code still requires numeric depth for compatibility. If compatibility requires numeric depth, document the exception in the pack README and fix the import code later.

Access

Valid access values:

• free
• premium

Category Access

Valid category access values:

• free
• premium
• mixed

3. JSON Structure

Category metadata

{
  "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

{
  "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" }
  ]
}

Daily single choice category metadata

{
  "id": "daily_single_choice_weekly_v1",
  "title": "Daily Single Choice",
  "access": "mixed",
  "description": "One weekday themed single choice question per day.",
  "count": 500,
  "free_count": 75,
  "premium_count": 425,
  "questions": []
}

Use daily_fun_multiple_choice_v3.json only as a temporary compatibility filename if the app still expects it. The content inside the file must still be single_choice.

Daily single choice question object

{
  "id": "daily_monday_001",
  "type": "single_choice",
  "text": "Long day. What would actually help tonight?",
  "depth": "light",
  "access": "free",
  "sex": "neutral",
  "tags": ["daily_monday_mood_check"],
  "options": [
    { "id": "hug_before_chores", "text": "A hug before chores" },
    { "id": "easy_dinner", "text": "Dinner without overthinking it" },
    { "id": "quiet_minutes", "text": "Ten quiet minutes together" },
    { "id": "tiny_task", "text": "One tiny task done" }
  ]
}

Daily question rules:

• Use single_choice only.
• Use 4 to 6 options.
• Use exactly one weekday tag.
• Every option must answer the prompt.
• Avoid therapy coded wording.

Weekday tags:

• daily_monday_mood_check
• daily_tuesday_tiny_win
• daily_wednesday_real_one
• daily_thursday_laugh
• daily_friday_flirty
• daily_saturday_side_quest
• daily_sunday_slow_burn

4. Validation Rules

Standard Packs

Every standard rewritten pack must pass:

• valid JSON
• exactly 250 questions
• 75 free
• 175 premium
• 140 multi_choice
• 50 single_choice
• 35 scale
• 15 this_or_that
• 10 written
• valid depth values only: light, medium, deep
• valid access values only: free, premium
• valid type values only: multi_choice, single_choice, scale, this_or_that, 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 choice question has options
• every scale question has scale configuration
• every written question has answer configuration
• every category contains fun, curiosity, and meaningful conversations

Daily Single Choice Weekday Packs

Every daily single choice weekday pack must pass:

• valid JSON
• metadata counts match actual counts
• exactly 500 questions unless a new documented app decision changes the count
• exactly 75 free questions
• exactly 425 premium questions
• every question is single_choice
• every question has 4 to 6 options
• every question has exactly one weekday tag
• every option directly answers the prompt
• no duplicate question IDs
• no duplicate question texts
• no exact repeated option lists
• no malformed keys
• no placeholder text
• no therapy worksheet tone
• no wellness survey tone
• no obvious AI repetition

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 or documented special pack rules.
• Free/premium counts match metadata.
• Depth values are valid or documented for compatibility.
• Access values are valid.
• Options have unique IDs inside each question.
• Option IDs are neutral and clean.
• Scale labels are present when needed.
• Every choice question has options.
• Every scale question has scale configuration.
• Every written question has answer configuration.
• No malformed keys.
• 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 or busy life
• date night stress
• memories
• future date dreams

Example for Daily Single Choice Weekday:

• easy dinner
• couch time
• small help
• hugs
• chores
• snacks
• little dates
• inside jokes
• errands together
• walks
• texts
• compliments
• kisses
• bedtime
• weekend plans
• tiny surprises

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?

Daily packs also fail if they have blocks like this:

Which reset would help tonight?
Which reset would help Monday?
Which reset would help us feel closer?
Which reset would help before bed?

Better:

Long day. What would actually help tonight?
What tiny nice thing would make Monday less annoying?
What would make the couch feel like a date tonight?
Before bed, what would feel sweetest?

7. Content Batching Process

Do not write all 250 questions in one creative pass.

Do not write all 500 daily questions in one creative pass.

Use this process:

1. Define pack purpose.
2. Define subtopics.
3. Write 20 to 30 sample questions for the target voice.
4. Review tone and repetition.
5. Fix the sample before scaling.
6. Write the next batch.
7. Add choice, scale, and this or that questions when used.
8. Assign free/premium.
9. Assign depth.
10. Validate JSON.
11. Read the full file like a user.