# 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 + single_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.

## single_choice

Select one best answer.

```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:

- 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?
```

## this_or_that

Very fast playful questions. Should take under three seconds.

```json
{
  "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.

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

Every 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% of all questions must be choice-based (multi_choice + single_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"
  }
}
```

## This-or-that question object

```json
{
  "id": "dn_089",
  "type": "this_or_that",
  "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",
  "answer": {
    "max_length": 500
  }
}
```

Written questions require an `answer` configuration with `max_length`.

---

# 4. Validation Rules

Every 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) — no numeric depth values
- 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

## 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 (light, medium, deep only).
- [ ] No numeric depth values.
- [ ] 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 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.
