lorraine

This document describes the current, simple question/response format used in the app, plus an optional appendix of advanced facets for future phases. The immediate goal is to collect high‑quality, easy‑to‑author pairs for LoRA fine‑tuning of “style transfer” with minimal metadata.

• Coverage: Capture the breadth of situations people respond to (work, personal, public, service, etc.).
• Control: Parameterize questions with facets (tone, formality, emotion, power dynamics) for targeted sampling.
• Parsimony: Achieve high coverage without exploding the cross‑product (via stratified/structured sampling).
• Privacy: Support redaction and sensitivity metadata.
• Trainability: Produce consistent, machine‑readable input/output pairs with rich metadata for conditioning.

Keep authoring dead‑simple so anyone (including kids/teens/non‑tech users) can contribute consistent data.

{
  "id": "string",
  "label": "short descriptive name",
  "instruction": "single instruction text (includes the scenario)",
  "tags": ["grouping", "filters"],
  "example": "a neutral, normal-human example reply (optional but recommended)"
}

Notes

• instruction merges the old instruction + source_text into one block. Write it in plain language.
• example replaces the old neutral_sample. It’s what a normal human might say; concise; no sensitive data.
• tags are lightweight for grouping/filters (e.g., friends, email, invite). No other fields are required.

File layout

• Files live under data/questions/ and may be sharded (e.g., work.json, friends.json, youth/school.json).
• Aggregation endpoints combine files as needed:
  • /data/questions/simple.json (all simple questions, recursive)
  • /data/questions/simple/by-groups.json?groups=work,friends (selected groups)

Authoring rules

• Keep instruction and example at a grade‑6 to grade‑9 reading level when possible.
• Use whitespace/newlines in instruction to separate “context” and “what to do.”
• Avoid extra formatting, bullet lists, or markup; keep it plain.
• Never include real PII in example; paraphrase.

UI presentation

• Title/label is not emphasized.
• The app shows a simple block:
  • “Instructions: ”
  • “Example: ” (always shown if present)

{
  "question_id": "string",
  "raw_response": "user’s answer in their voice",
  "created_at": "ISO 8601",
  "neutral_distance_note": "optional freeform note",
  "response_latency_ms": 1234
}

Notes

• raw_response captures exactly how the user would say it. No polishing required.
• neutral_distance_note is optional (e.g., “I’d be more direct here than the example”).

• Low friction: fewer fields → faster authoring and better completion rates.
• Style focus: instruction + example give enough context to generate user‑style responses.
• Simple conditioning: tags enable basic slicing without heavy metadata.

The following facets are NOT required for the current collection, but remain useful if we later need more control or analysis. Treat them as an optional overlay stored separately or added in a later phase.

• Domain/context: work, school/academia, family, partner, friends, social, public, customer support, sales, legal/admin, healthcare, travel/hospitality, community/volunteer, gaming, developer/collab (GitHub/PRs).
• Channel/medium: in‑person, phone/voice, video, SMS/iMessage, WhatsApp, Slack/Teams, email, calendar invite, social post (X/IG/LinkedIn/TikTok caption), comment/reply, forum/Discord, GitHub issue/PR/review, blog, support ticket, survey, form.
• Audience role: manager, direct report, peer, cross‑functional partner, vendor, customer, friend (close), friend (acquaintance), partner/spouse, child/parent/sibling, professor/TA/student, doctor/therapist, government/agency.
• Relationship closeness: stranger, acquaintance, familiar, close, intimate.
• Power dynamics: subordinate → equal → senior; high/low leverage; high/low stakes.
• Formality: very informal, informal, neutral, formal, very formal.
• Tone/voice: friendly, warm, enthusiastic, calm, concise, direct, diplomatic, firm, empathetic, humorous, witty, serious, inspirational, authoritative, deferential.
• Emotion state (author of response): use circumplex (valence: negative↔positive, arousal: low↔high) and/or Plutchik categories (anger, fear, sadness, disgust, surprise, anticipation, trust, joy) with intensities.
• Emotion target: self‑oriented vs other‑oriented; directed at person vs topic vs situation.
• Speech act / intent: ask/request, propose, inform, confirm, deny, clarify, instruct, announce, invite, accept, decline, schedule, reschedule, apologize, thank, congratulate, praise, critique, give feedback, complain, escalate, negotiate, set boundary, follow up, remind, nudge, check in, summarize, debrief, reflect.
• Urgency/time pressure: none, low, medium, high, crisis.
• Constraints: length (very short, short, medium, long), bullets vs paragraph, with/without emoji, with/without links, subject line required, call‑to‑action required, deadline date/time, reading level.
• Sensitivity/compliance: PII present, confidential, legal exposure, HR policy, medical/financial, regulated industry, brand guideline needed.
• Cultural/region/language: locale (en‑US, en‑UK, en‑IN, etc.), politeness norms, honorifics, code‑switching preferences.
• Time/contextual anchors: time of day, weekday/weekend, before/after an event (launch, outage, interview, exam), proximity to deadline.
• Topic domain: engineering, product, design, marketing, sales, ops, finance, HR, education, research, creative, household/admin, travel, events.
• Formatting preferences: greetings/closings style, signature block, bullets, numbering, sections, TL;DR, action list.
• Style modifiers (pragmatics): directness, hedging, intensifiers, face‑saving, humor level, exclamation usage, emoji usage, colloquialisms, slang.

• MBTI (16 types): e.g., INTJ, ENFP. Store declared type or unknown.
• Big Five (OCEAN): scores 0–100 per trait.
• Enneagram: types 1–9, optional wing.
• DiSC: D/I/S/C primary and secondary.
• Communication preferences: directness (1–5), candor (1–5), warmth (1–5), humor (1–5), emoji usage (never→often), exclamation tolerance, sentence length preference, bullet vs paragraph preference.
• Professional voice toggles: brand voice adjectives, do/don’t words, signature/greeting conventions.

If/when needed, we can layer additional fields (domain, channel, tone, etc.) as a separate metadata file or by expanding items. See the earlier version of this document for the full list of optional fields.

Advanced fields like polished_response, self_ratings, or derived metrics can be added later if we need deeper analysis. For now we only capture the minimal fields listed above.

• Domain/context

  • Work: 1:1, standup, status update, project kickoff, code review, PR description, incident postmortem, performance review, promotion/raise ask, interview scheduling, offer negotiation, vendor management.
  • Personal: partner check‑in, apology, boundary setting, planning a trip, money talk, household admin, parenting.
  • Friends/social: invite, RSVP, plan details, jokes/banter, group coordination, conflict resolution.
  • Public/social: announcement, thread reply, correction, hot take, event recap, launch post, mea culpa.
  • Service/support: report an issue, ask for refund, give praise, complaint escalation.
  • Admin/legal: lease inquiry, government forms, policy appeal.
  • Healthcare: appointment request, symptoms note, follow‑up question, insurance paperwork.
  • Travel/hospitality: booking request, change/reschedule, special request.
  • Education: email professor, TA feedback, peer review, assignment clarification.
  • Developer collaboration: GitHub issue, PR summary, code review comment, RFC response, design doc feedback.

• Speech act / intent (canonical set)

  • Ask/request, propose/suggest, inform/update, confirm/deny, clarify, instruct, announce, invite, accept/decline, schedule/reschedule, apologize, thank, congratulate, praise, critique, feedback, complain, escalate, negotiate, set boundary, follow up, remind, nudge, check in, summarize, debrief, reflect.

• Tone/voice (mix‑and‑match)

  • Friendly, warm, calm, concise, direct, diplomatic, firm, empathetic, humorous, witty, serious, inspirational, authoritative, deferential.

• Stratified grid: Choose anchor levels for key axes: domain × channel × speech_act × (formality: low/med/high) × (valence: −/0/+) × (power: sub/equal/senior).
• Latin hypercube sampling across remaining facets (tone modifiers, constraints, topic domains) to ensure even coverage.
• Phase coverage quotas (suggested minima):
  • Work (email, Slack, PR/GitHub): 40–60 items
  • Personal/partner/family: 20–30
  • Friends/social: 20–30
  • Public/social media: 15–25
  • Service/support/admin: 15–25
  • Education/healthcare/travel: 10–20
  • Emotions sweep (same scenario across −/0/+ valence and low/high arousal): 15–25

• Work – status update (email, neutral): “Share a brief project status with next steps and date‑based milestones.”
• Work – request (Slack, equal): “Ask a peer to review your PR today.”
• Work – escalate (email, senior): “Escalate a blocker with clear impact and request for decision.”
• Work – feedback (1:1 note): “Give constructive feedback on missed deadline; keep rapport.”
• Work – negotiation (email): “Negotiate timeline extension by one week; offer trade‑offs.”
• Developer – PR summary: “Write a PR description summarizing changes, risks, and testing notes.”
• Developer – code review: “Request changes on a PR; be specific and respectful.”
• Personal – apology: “Apologize for being late to dinner; own it and propose a make‑good.”
• Personal – boundary: “Decline an invitation without hurting feelings.”
• Friends – planning: “Coordinate a group dinner; propose 2 dates and a budget.”
• Friends – banter: “Respond playfully to a joke; keep it light.”
• Partner – check‑in: “Express appreciation after a tough week.”
• Public – announcement: “Post about launching a small tool; concise and authentic.”
• Public – correction: “Correct misinformation politely in a thread.”
• Support – refund: “Request a refund for a faulty product; include order details.”
• Support – praise: “Thank a customer support rep for great service.”
• Admin – policy appeal: “Appeal a parking ticket; state facts and request leniency.”
• Healthcare – appointment: “Ask to move an appointment earlier; mention symptom severity.”
• Travel – change flight: “Request flight change due to conflict; provide preferences.”
• Education – email professor: “Ask for clarification on assignment requirements.”

Each template becomes a question by binding facets (channel, tone, formality, etc.) and a concrete source_text stimulus.

• Instruction template: “Reply in your own voice, matching the specified tone and constraints.”
• Context block: scenario summary + source_text (if provided) + facets.
• Constraints: explicit bullets (length, emoji, bullets vs paragraph, deadline).

Example assembled question (human‑readable):

• Label: Work email follow‑up (neutral, concise)
• Instruction: Reply in your own voice. Keep it concise and warm. Include a clear ask.
• Source text: “Circling back on the Q3 deliverables: can you share an updated timeline by Friday?”
• Facets: domain: work; channel: email; audience: peer; power: equal; formality: neutral; tone: [concise, warm]; speech_act: [follow_up, request]; urgency: medium.

• Files
  • data/questions/*.json: question banks by domain/group (simple schema above).
  • data/responses/*.jsonl: user responses (one JSON per line) using the minimal response schema.
  • schemas/question.schema.json, schemas/response.schema.json: JSON Schemas for validation.

• For legacy items with neutral_sample, the app treats it as example.
• Old source_text is now merged into instruction.

• Phase 1: ship with minimal schema (current). Focus on breadth and ease of authoring.
• Phase 2 (optional): add overlays for emotions/power/tone on a subset if needed.
• Phase 3 (optional): domain deep dives with richer metadata if training analysis demands it.

• Built‑in redaction UI; sensitivity flags; local‑first storage options.
• Guidance to paraphrase sensitive specifics while preserving style markers.

• Implement JSON Schemas and a generator that samples templates × facets with quotas.
• Build a UI that presents scenario + facets clearly, collects responses, self‑ratings, and optional rationale.
• Add analytics to track coverage across facets and identify gaps for targeted sampling.