Closer/seed/questions/QUESTION_CONTENT_GUIDE.md

# Closer Question Content Guide

## Purpose

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, or like therapy homework.

Use this guide before writing or rewriting any question JSON file.

## Pack Size Authority

Normal category packs may contain **up to 150 questions**. The 150-question limit is a ceiling, not a quota. Use fewer questions when the topic cannot support 150 distinct, strong prompts without filler or repetition.

Only a documented product-specific special pack may exceed 150 questions. The current daily single-choice weekday system is one such exception and keeps its separately documented 511-question total.

Written questions must remain rare. A normal pack may use **0 to 5 written questions by default**. More than 5 requires a documented pack-specific reason and explicit product-owner approval. Never use written questions to fill a count.

## Importer and Production Contract Authority

The active app importer and Room database contract are authoritative for production JSON.

Human-friendly authoring labels, batch notes, patch manifests, and planning files may help writers work, but they must never replace or override the production schema.

Current production rules:

- a production pack must use the top-level shape `{ "category": {...}, "questions": [...] }`
- the `category` object is required and must include `id`, `display_name`, `description`, `access`, and `icon_name`
- every question must include `id`, `category_id`, `type`, `text`, integer `depth`, `access`, and `tags`
- `category_id` must exactly match `category.id`
- `depth` must be an integer: `1` = light, `2` = medium, `3` = deep
- `tags` must be present as an array; use at least one meaningful tag unless a documented exception exists
- `sex` is optional and nullable for ordinary packs; require it only when a product feature actually filters or routes by sex
- question-type-specific fields must match `QUESTION_SCHEMA.md`
- never rely on the filename to create or repair a missing category
- a batch file, continuation note, validation report, or patch manifest is not a production question pack

When a writing document conflicts with the importer, stop and correct the writing document. Do not ship compatibility-breaking JSON and do not defer the mismatch to a future importer change.

---

# 1. The Closer Voice

Closer should sound:

- 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

## Voice rule

A good Closer question should sound like something a real person could comfortably ask their partner.

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

---

# 2. Core Writing Standard

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

If the answer is no, rewrite it.

---

# 3. Product Goal

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

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

---

# 4. 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=
```

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

---

# 5. Question Depth Levels

Use depth intentionally.

The writing concepts are Light, Medium, and Deep, but the production JSON field is numeric:

| Writing concept | Production `depth` |
|---|---:|
| Light | `1` |
| Medium | `2` |
| Deep | `3` |

Never write `"light"`, `"medium"`, or `"deep"` into a production question object. Those labels may appear only in planning notes, coverage maps, or human-readable review documents.

## Future depth migration — not production-ready

String depth values such as `"light"`, `"medium"`, and `"deep"` are a possible future schema direction.

They are **not valid production values today**.

Do not use string depth until one coordinated engineering change updates and verifies all of the following:

```text
build_db.py
Room entity and column type
database migration or asset rebuild path
all getInt()/integer readers
depth routing and help text
seed validation
automated tests
existing production JSON
```

Until that migration is merged and deployed, production JSON must use integers `1`, `2`, or `3`.


## Light

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

## Medium

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

## Deep

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

## 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.
```

---

# 6. Question Types

Every production example in this section matches the importer contract used today.

`sex` is omitted because it is optional for ordinary packs. Add it only when a documented feature needs it.

## written

Use written questions only when a choice-based format would lose the story, nuance, or personal explanation.

A normal pack should contain 0 to 5 written questions unless a documented exception is approved.

```json
{
  "id": "emotional_intimacy_001",
  "category_id": "emotional_intimacy",
  "type": "written",
  "text": "What is one recent moment when you felt especially close to me?",
  "depth": 2,
  "access": "free",
  "tags": ["recent_memory", "closeness", "emotional_intimacy"],
  "answer_config": {
    "max_length": 500
  }
}
```

Rules:

```bat
ECHO Use answer_config for written settings.
ECHO max_length is required when a custom limit matters.
ECHO Do not use a top-level answer object.
ECHO Do not use written questions for basic preferences.
ECHO Do not use written questions to fill the pack count.
```

Avoid:

```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 when the player should choose one best answer.

```json
{
  "id": "date_night_001",
  "category_id": "date_night",
  "type": "single_choice",
  "text": "Which kind of date sounds best this week?",
  "depth": 1,
  "access": "free",
  "tags": ["date_preference", "planning", "date_night"],
  "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" }
  ],
  "answer_config": {
    "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" }
    ]
  }
}
```

Rules:

```bat
ECHO Use 4 to 6 options by default.
ECHO Options should be short and natural.
ECHO Every option must directly answer the prompt.
ECHO Options should be similar in effort and emotional weight.
ECHO Mirror top-level options into answer_config.options exactly.
```

---

## multi_choice

Use when more than one answer can be true.

```json
{
  "id": "date_night_002",
  "category_id": "date_night",
  "type": "multi_choice",
  "text": "What helps you feel relaxed on a date with me?",
  "depth": 1,
  "access": "free",
  "tags": ["comfort", "date_preferences", "date_night"],
  "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" }
  ],
  "answer_config": {
    "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" }
    ],
    "min_selections": 1,
    "max_selections": 3
  }
}
```

Rules:

```bat
ECHO The prompt should clearly allow multiple answers.
ECHO Options should not shame either partner.
ECHO Options should not overlap excessively.
ECHO Mirror top-level options into answer_config.options exactly.
```

---

## scale

Use for one measurable dimension such as comfort, closeness, energy, readiness, satisfaction, confidence, importance, or frequency.

```json
{
  "id": "date_night_003",
  "category_id": "date_night",
  "type": "scale",
  "text": "How much would a real date help us feel connected right now?",
  "depth": 2,
  "access": "free",
  "tags": ["connection", "readiness", "date_night"],
  "answer_config": {
    "min": 1,
    "max": 5,
    "min_label": "Not much",
    "max_label": "A lot"
  }
}
```

Rules:

```bat
ECHO Put scale settings inside answer_config.
ECHO Do not use a top-level scale object.
ECHO min, max, min_label, and max_label are required for custom labels.
ECHO Scale labels should be gentle and neutral.
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 a fast two-option choice.

```json
{
  "id": "date_night_004",
  "category_id": "date_night",
  "type": "this_or_that",
  "text": "Planned date or spontaneous date?",
  "depth": 1,
  "access": "free",
  "tags": ["quick_choice", "date_style", "date_night"],
  "options": [
    { "id": "planned_date", "text": "Planned date" },
    { "id": "spontaneous_date", "text": "Spontaneous date" }
  ],
  "answer_config": {
    "options": [
      { "id": "planned_date", "text": "Planned date" },
      { "id": "spontaneous_date", "text": "Spontaneous date" }
    ]
  }
}
```

Rules:

```bat
ECHO Supply exactly two options.
ECHO Do not ship a bare this_or_that prompt with no options.
ECHO Mirror top-level options into answer_config.options exactly.
ECHO Keep both choices balanced and easy to understand.
```

---


# 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

Avoid these unless there is a very good reason.

```text
What boundary around...
hold space
emotional container
relationship dynamic
intentional intimacy
deepen our connection
in this season
needs met
love language
safe space
show up for you
lean into
create space for
feel seen and heard
navigate conflict
honor your needs
```

These phrases are not always wrong, but they quickly make the app sound generic or clinical.

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

## Fun packs

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

Avoid:

```text
How can we optimize shared leisure experiences?
```

---

## Date Night packs

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

Avoid:

```text
What date structure would best support our connection goals?
```

---

## Boundaries packs

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

Avoid:

```text
What boundary around boundaries would support emotional safety?
```

---

## Conflict packs

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

Avoid:

```text
What do I always do wrong during conflict?
```

---

## Trust packs

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

Avoid:

```text
What have I done to make you unable to trust me?
```

---

## Sex, desire, and physical intimacy packs

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

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

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

---

# 10. Safety Rules

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

## Abuse-sensitive rule

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

## Consent rule

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

---

# 11. Wording Rules

## Keep questions short

Aim for 8 to 22 words when possible.

Long questions are okay only when the topic needs softness or context.

## Ask one thing at a time

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

## Avoid stacked emotional words

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

Bad:

```text
How can we be more connected?
```

Better:

```text
What is one thing we could do tonight to feel closer?
```

## Avoid blame

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. Production JSON Contract and Quality Rules

A JSON file is production-ready only when it is both valid content and a complete importable pack.

## 12.1 Required top-level shape

Every production pack must use:

```json
{
  "category": {
    "id": "example_category",
    "display_name": "Example Category",
    "description": "User-facing description.",
    "access": "mixed",
    "icon_name": "favorite"
  },
  "questions": []
}
```

Required category fields:

```text
id
display_name
description
access
icon_name
```

Optional category fields such as `schema_version` and `metadata` may be included, but they do not replace the required fields.

Do not use the old simple-pack shape:

```json
{
  "id": "example",
  "title": "Example",
  "count": 25,
  "questions": []
}
```

Do not rely on filename parsing to create a category. A missing `category` object is a hard production failure.

## 12.2 Required question fields

Every production question must include:

```text
id
category_id
type
text
depth
access
tags
```

Rules:

- `category_id` must exactly equal the enclosing `category.id`
- `depth` must be the integer `1`, `2`, or `3`
- `tags` must be an array and should contain at least one meaningful tag
- `access` must be `free` or `premium`
- `sex` is optional and nullable for ordinary category packs
- `sex` becomes required only for a documented feature that routes or filters by it
- choice options and `answer_config` must follow `QUESTION_SCHEMA.md`
- top-level `options` and `answer_config.options` must match when both are required by the active schema


## 12.2A Type-specific importer contract

The active importer reads:

| Type | Production source |
|---|---|
| `single_choice` | top-level `options`; mirror into `answer_config.options` |
| `multi_choice` | top-level `options`; mirror into `answer_config.options` |
| `this_or_that` | exactly two top-level `options`; mirror into `answer_config.options` |
| `scale` | `answer_config.min`, `max`, `min_label`, `max_label` |
| `written` | `answer_config`, including `max_length` when customized |

Do not place scale settings in a top-level `scale` object.

Do not place written settings in a top-level `answer` object.

Do not ship `this_or_that` without two explicit choices.


## 12.3 Production pack versus work artifact

These are not production packs:

```text
25-question batch files
continuation notes
coverage maps
validation reports
marked-fix lists
patch manifests
apply scripts
review summaries
```

A work artifact must never overwrite a production filename.

A partial batch may be saved only outside importer-scanned production directories and must be clearly labeled as work in progress. The last complete validated production pack stays in place until the full replacement is ready.

A patch manifest must:

- use a clearly non-production name such as `*.patch.json`
- live outside any importer-scanned production directory
- identify the complete source pack it applies to
- be applied to the full source pack
- produce a complete validated production JSON before shipping

A patch manifest is never itself renamed to the production filename.

## 12.4 Daily pack protection

`daily_fun_multiple_choice_v3.json` is the compatibility filename for the Daily Single-Choice Weekday System.

That production file must always contain the complete documented pack:

```text
500 weekday questions
11 wildcard questions
511 total questions
86 free
425 premium
511 single_choice
```

A daily patch document containing only changed IDs is not the daily pack. Restore or retain the complete 511-question source, apply the patch to that source, then validate and ship the complete result.

## 12.5 Per-file hard checks

```bat
ECHO [ ] Valid JSON.
ECHO [ ] Top-level category object exists.
ECHO [ ] Top-level questions array exists.
ECHO [ ] Category contains id, display_name, description, access, and icon_name.
ECHO [ ] Category id matches the file purpose.
ECHO [ ] Category title and description are user-facing.
ECHO [ ] Metadata counts match actual question counts.
ECHO [ ] Every question has category_id matching category.id.
ECHO [ ] Every question has integer depth 1, 2, or 3.
ECHO [ ] Every question has an access value of free or premium.
ECHO [ ] Every question has a tags array.
ECHO [ ] All question IDs are unique inside the file.
ECHO [ ] All question texts are unique inside the file.
ECHO [ ] No near-duplicate blocks remain.
ECHO [ ] Type counts match metadata.
ECHO [ ] Free/premium counts match metadata.
ECHO [ ] Options have unique IDs inside each question.
ECHO [ ] Option IDs are neutral and clean.
ECHO [ ] Choice options mirror answer_config where required.
ECHO [ ] Scale labels are present when needed.
ECHO [ ] Written answer limits are present when needed.
ECHO [ ] No malformed keys.
ECHO [ ] No placeholder text.
ECHO [ ] The file is a complete pack, not a batch or patch artifact.
```

Valid access values:

```text
free
premium
```

Valid category access values:

```text
free
premium
mixed
```

Valid production depth values:

```text
1
2
3
```

Valid question types:

```text
written
single_choice
multi_choice
scale
this_or_that
```

## 12.6 Catalog-wide hard gate

Per-file validation is not enough.

Before rebuilding `app.db` or shipping question content, validate every production pack together.

The full catalog must have:

- globally unique question IDs
- globally unique exact question text
- no normalized duplicate question text after case and whitespace normalization
- no blocked near-duplicates across categories
- no production filename containing a patch or partial batch
- no category resolving to `unknown`
- no schema mismatch that would coerce or zero a field

A duplicate in two different category files is still a hard failure. The importer may abort the entire build, not merely skip the duplicate question.

When the same idea belongs in two packs, rewrite each prompt around its category-specific purpose rather than copying the same text.

## 12.7 Catalog impact reporting

When replacing or trimming an existing pack, report:

```text
old question count
new question count
net catalog change
old free/premium counts
new free/premium counts
whether the change is intentional and approved
```

A planned reduction from a legacy 250-question pack to a stronger 150-question pack is not a schema defect, but the live catalog shrink must be visible in the completion report.


# 13. Pack Structure Recommendation

Normal category packs may contain **no more than 150 questions**. A complete 150-question mixed pack should normally target:

```bat
SET TOTAL_QUESTIONS=150
SET FREE_QUESTIONS=45
SET PREMIUM_QUESTIONS=105
SET MULTI_CHOICE=90
SET SINGLE_CHOICE=30
SET SCALE=15
SET THIS_OR_THAT=10
SET WRITTEN=5
```

This mix is a planning target, not permission to add filler. A smaller pack is valid when the topic cannot support 150 distinct, strong questions.

Rules:

- 150 is the maximum for a normal category pack.
- written questions should normally total 0 to 5
- do not force every pack to use every question type
- preserve the intended free/premium value split when using a smaller pack
- only a documented special product pack may exceed 150
- the 511-question daily single-choice system is a documented special exception

---

# 14. Required Batch Writing Workflow

Question packs must not be written in one uninterrupted bulk-generation pass.

A normal category pack may contain up to 150 questions. Only a documented special product pack may exceed that limit. Regardless of final size, question creation must be divided into controlled batches so quality, continuity, counts, and repetition can be reviewed throughout the work.

## 14.0 Production Replacement Rule

Batching controls the writing process; it does not redefine the production file.

During a multi-batch rewrite:

1. Keep the last complete production pack intact.
2. Draft and review each batch in a clearly labeled work artifact or controlled workspace.
3. Never overwrite the production filename with only the completed batches so far.
4. Never change the production file to a simple batch schema.
5. Merge reviewed batches into the complete `{ "category": ..., "questions": [...] }` pack.
6. Run per-file validation.
7. Run the catalog-wide duplicate and import validation.
8. Replace the production file only with the complete validated result.

A continuation note may say `Next ID: ...`; that does not make the partial JSON shippable.

## 14.1 Batch Size

Write exactly 25 new questions per batch.

Do not begin the next batch until the current batch has completed the required review, correction, validation, and continuity update.

Use a smaller batch of 15–20 questions for:

- sensitive or emotionally heavy topics
- conflict and repair
- sex, desire, or physical intimacy
- trauma-adjacent subjects
- questions requiring identity-specific targeting
- unusually complicated answer options
- packs with difficult safety or consent requirements

Never write more than 25 new questions in one writing pass unless the task contains a documented exception approved by the product owner.

A request to create or rewrite an entire pack is not permission to generate the whole pack in one pass.

## 14.2 Required Files to Read Before Writing

Before writing the first batch, read:

1. `QUESTION_CONTENT_GUIDE.md`
2. `QUESTION_QUALITY_CHECKLIST.md`
3. `QUESTION_SCHEMA.md`
4. the target question JSON file, when it already exists
5. any pack-specific notes or rewrite instructions
6. closely related packs that may overlap in topic, wording, or mechanics
7. the current coverage map or continuation note, when work has already started

Do not begin writing until the pack requirements and existing content are understood.

## 14.3 Define the Pack Before Drafting

Before creating questions, define:

```bat
SET PACK_NAME=
SET PACK_PURPOSE=
SET USER_FEELING=
SET RELATIONSHIP_OUTCOME=
SET FREE_VALUE=
SET PREMIUM_VALUE=
SET TOTAL_QUESTIONS=
SET FREE_QUESTIONS=
SET PREMIUM_QUESTIONS=
```

Also define:

- intended audience
- tone
- safety level
- question-type distribution
- depth distribution
- free/premium strategy
- subtopics
- special targeting rules
- topics to avoid
- related packs that must not be duplicated

## 14.4 Create a Full-Pack Coverage Map

Create a lightweight plan for the complete pack before drafting the first 25 questions.

The coverage map should assign each planned question or ID range:

- question ID or ID range
- question type
- free or premium access
- depth
- topic or subtopic
- intended emotional effect
- game mechanic or conversation goal
- approximate position in the pack
- special safety or targeting requirements

The coverage map is a planning tool. It is not approval to generate every planned question at once.

The map should make it possible to see whether the full pack will have enough variety before large amounts of content are written.

## 14.5 Required 25-Question Loop

Use this exact loop for every batch:

```bat
ECHO Step 1: Review the coverage map for the next 25 IDs.
ECHO Step 2: Re-read the Critical Batch Reminder.
ECHO Step 3: Review the previous completed batch.
ECHO Step 4: Review the pack-wide repetition and continuity notes.
ECHO Step 5: Write only the next 25 questions.
ECHO Step 6: Stop generating new questions.
ECHO Step 7: Validate the batch against the schema.
ECHO Step 8: Review every question against this guide and the quality checklist.
ECHO Step 9: Read every prompt and its answer options aloud.
ECHO Step 10: Mark every failed question by ID and reason.
ECHO Step 11: Fix only the marked questions.
ECHO Step 12: Review every corrected question again.
ECHO Step 13: Confirm zero unresolved hard failures.
ECHO Step 14: Update counts, coverage, repetition notes, and the continuation note.
ECHO Step 15: Only then begin the next batch.
```

Do not continue into the next batch merely because the JSON parses.

Do not silently skip the review because the first draft appears acceptable.

## 14.6 Critical Batch Reminder

Before writing every batch, confirm:

```bat
ECHO Closer is a couples game, not therapy homework.
ECHO Each question should create a laugh, flirt, discovery, memory, shared plan, appreciation, or meaningful couple moment.
ECHO Questions must sound natural when read aloud.
ECHO Questions must be clear in one read.
ECHO Choice options must directly and grammatically answer the prompt.
ECHO Options must be balanced in effort, emotional weight, and intimacy.
ECHO Written questions must earn the keyboard.
ECHO Avoid repeated stems, scenarios, mechanics, jokes, and answer patterns.
ECHO Do not write filler to complete a quota.
ECHO Do not rewrite passing questions without a documented reason.
ECHO Sensitive questions must remain consent-first, optional, and non-coercive.
```

## 14.7 Batch Review Requirements

Review all 25 questions individually.

Check each question for:

- natural human wording
- pack and category fit
- subtopic fit
- depth accuracy
- correct question type
- correct free or premium placement
- schema correctness
- prompt-to-option compatibility
- balanced answer choices
- usefulness as a couples-game moment
- appropriate emotional weight
- similarity to existing questions
- similarity to earlier batches
- repeated sentence structures
- repeated options
- repeated mechanics
- therapy, worksheet, survey, or corporate language
- household-administration or chore language when not appropriate
- pressure, blame, shame, coercion, or unsafe assumptions
- unnecessary gendering or stereotypes
- whether the question is worth paying for when marked premium

For choice questions, read the prompt followed by each option as one sentence.

If an option does not grammatically or logically answer the prompt, rewrite it.

If two or more options fail, review and rewrite the full answer set rather than patching isolated words.

## 14.8 Failure Tracking and Targeted Fixes

Each failed question must be recorded with:

- question ID
- failure reason
- required fix scope
- whether the prompt, options, metadata, or full question must change
- replacement or correction status
- re-review result

Fix only failed questions.

Do not regenerate passing questions merely to make the batch look more consistent.

A batch is complete only when every marked failure has been corrected and re-reviewed.

## 14.9 Fifty-Question Checkpoint

After every two completed batches, stop and review the full set of 50 questions together.

Check for patterns that may not be obvious inside a 25-question batch:

- repeated opening phrases
- repeated sentence rhythms
- repeated jokes, metaphors, or scenarios
- mechanic overuse
- topic imbalance
- subtopic gaps
- depth imbalance
- type imbalance
- free/premium imbalance
- weak transitions
- clusters of heavy questions
- clusters of nearly identical questions
- option wording reused across questions
- premium questions that do not feel more valuable
- questions that belong in another pack

Fix only IDs that fail.

Update the coverage map, counts, repetition notes, and continuation note before writing more questions.

## 14.10 One-Hundred-Question Context Refresh

After every 100 completed questions:

1. Re-read the full `QUESTION_CONTENT_GUIDE.md`.
2. Re-read `QUESTION_QUALITY_CHECKLIST.md`.
3. Re-read `QUESTION_SCHEMA.md`.
4. Review the pack definition and coverage map.
5. Review all checkpoint notes.
6. Recalculate completed and remaining counts.
7. Check whether the second half of the pack is becoming repetitive or lower quality.
8. Adjust only the unwritten coverage plan unless an existing question has a documented failure.

Also perform this full context refresh whenever:

- quality begins to drift
- repeated failures appear
- the work resumes in a new session
- the model loses reliable context
- requirements change
- a pack-specific note is added
- the schema changes

## 14.11 Required Continuation Note

At the end of every batch, create or update a concise continuation note.

The continuation note is the source of truth when work resumes.

It must contain:

```text
Pack:
Target file:
Guide/schema versions used:
Completed ID range:
Next ID range:
Total completed:
Total remaining:
Type counts completed:
Type counts remaining:
Free count completed:
Premium count completed:
Free count remaining:
Premium count remaining:
Depth counts completed:
Depth counts remaining:
Subtopics already covered:
Mechanics already used:
Repeated wording to avoid:
Related-pack overlaps to avoid:
Failed IDs still unresolved:
Last checkpoint completed:
Next batch coverage:
Special safety or targeting notes:
```

Do not rely only on conversational memory or a temporary task list.

When resuming work, read the continuation note before generating anything new.

## 14.12 Session Resume Procedure

When work continues in a new session or context:

1. Read this guide.
2. Read the quality checklist and schema.
3. Read the target JSON.
4. Read the continuation note.
5. Verify the last completed ID.
6. Verify actual counts in the JSON instead of trusting the note blindly.
7. Review the previous 25 questions.
8. Review the next planned coverage.
9. Continue from the first unwritten or unresolved ID.

Never restart the pack from the beginning unless explicitly instructed.

Never overwrite completed, passing work because prior conversational context is unavailable.

## 14.13 Existing-Pack Rewrite Workflow

When revising an existing pack:

1. Audit the existing pack before rewriting.
2. Mark failed IDs and reasons.
3. Group failures into batches of no more than 25 IDs.
4. Rewrite only those failed IDs.
5. Preserve passing questions, IDs, access, and metadata unless a documented correction requires a change.
6. Review each corrected batch.
7. Run a 50-question cross-check after every two correction batches.
8. Run the final full-pack audit.

Do not mass-regenerate an existing pack by default.

A mass rewrite is allowed only when:

- more than 60% of the pack fails for the same root cause
- targeted correction would create more inconsistency than replacement
- the reason is documented
- the product owner has approved the exception

Even an approved mass rewrite must still use 25-question batches.

## 14.14 Final Full-Pack Audit

After all planned questions have been written or corrected:

1. Validate the complete JSON file.
2. Confirm the top-level shape is `{ "category": ..., "questions": [...] }`.
3. Confirm the category object contains every required field.
4. Confirm every question has `category_id` matching `category.id`.
5. Confirm every question uses integer depth `1`, `2`, or `3`.
6. Confirm every question has a tags array.
7. Confirm all IDs are unique inside the file.
8. Confirm all question texts are unique inside the file.
9. Confirm total question count.
10. Confirm question-type distribution.
11. Confirm free and premium distribution.
12. Confirm targeting fields.
13. Run exact duplicate checks inside the file.
14. Run near-duplicate checks inside the file.
15. Run repeated-stem and repeated-option checks.
16. Review subtopic coverage.
17. Review emotional-depth spacing.
18. Review mechanic distribution.
19. Review free-to-premium progression.
20. Read a representative sample from every section aloud.
21. Mark every failure by ID and reason.
22. Patch only failed IDs.
23. Re-run every affected validation and review check.
24. Run the full-catalog global ID and question-text duplicate gate.
25. Confirm no production filename contains a patch manifest or partial batch.
26. Report the old count, new count, and net catalog change.

The pack may ship only when:

```bat
ECHO The JSON parses.
ECHO The production top-level shape is category plus questions.
ECHO Required category fields exist.
ECHO Every category_id matches category.id.
ECHO Metadata counts match actual counts.
ECHO IDs are unique inside the pack and across the catalog.
ECHO Question texts are unique inside the pack and across the catalog.
ECHO Free/premium counts match.
ECHO Type counts match.
ECHO Depth values are integers 1, 2, or 3.
ECHO Tags exist on every question.
ECHO Required targeting fields are valid.
ECHO The file is a complete pack, not a patch or partial batch.
ECHO No unresolved hard failures remain.
ECHO No unacceptable repetition remains.
ECHO The full catalog import gate passes.
ECHO The final sample sounds natural and enjoyable aloud.
ECHO The tone guide was followed.
```

## 14.15 Quality Takes Priority Over Pack Size

A product target of 150 questions does not justify filler. The maximum is not a quota.

If the topic cannot support the planned count without repetition:

1. stop writing
2. document the repetition risk
3. identify whether the pack should be reduced or divided
4. recommend a revised count or pack split
5. wait for the product decision before adding filler

The preferred workflow is:

```text
Plan the whole pack.
Write 25.
Stop.
Review.
Fix.
Update continuity.
Write the next 25.
```

---

# 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

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

---

# 18. Claude Instructions for Rewriting JSON Packs

When Claude rewrites a pack:

```bat
ECHO Read the existing JSON first.
ECHO Treat the active importer and Room contract as schema authority.
ECHO Preserve the production shape: category object plus questions array.
ECHO Use integer depth 1, 2, or 3.
ECHO Add category_id and tags to every production question.
ECHO Keep sex optional unless the pack-specific feature requires it.
ECHO Preserve required counts unless an approved rewrite changes them.
ECHO Never overwrite a production filename with a partial batch.
ECHO Never overwrite a production filename with a patch manifest.
ECHO Apply patches to the complete source pack and return the complete JSON.
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 per file and across the full catalog.
ECHO Report old count, new count, and net catalog change.
ECHO Report any schema changes.
```

Claude should not say a file is done unless:

```bat
ECHO The JSON parses.
ECHO The file is a complete production pack.
ECHO The category object and questions array exist.
ECHO Required category and question fields exist.
ECHO The counts match.
ECHO Depth values are integers 1, 2, or 3.
ECHO IDs are unique inside the pack and across the catalog.
ECHO Question texts are unique inside the pack and across the catalog.
ECHO Free/premium counts match.
ECHO Type counts match.
ECHO The catalog import gate passes.
ECHO The tone guide was followed.
```

---

# 19. 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?
What is one date we should bring back?
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?
What helps you feel trusted instead of checked up on?
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?
What makes a hard conversation feel safer?
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?
What would make tonight feel less boring?
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?
What is one promise that matters a lot to you?
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?
What small affectionate habit would you like more of?
What makes cuddling or closeness feel safe and easy?
```

---

# 20. Final Standard

A finished Closer question pack should feel:

```text
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.

---

# 21. 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.