voice

Voice — Voice Elicitation Interview Engine

Voice is an adaptive voice elicitation interview engine that builds a comprehensive written-voice profile through a structured conversational interview. The engine administers 60-80 questions across 12 thematic modules, adapting its path based on the participant's responses and detected writer type.

Architecture Overview

• Question Bank: JSON question files organized by module in question-bank/modules/, validated against question-bank/schemas/question.schema.json
• Branching Logic: Conditional paths in question-bank/branching/ that route participants through writer-type-specific question sequences
• NLP Pipeline: Text analysis stages in nlp/ that extract stylistic signals from open-ended and writing-sample responses
• Scoring Engine: Dimension scoring in scoring/ that maps responses to voice profile dimensions with weighted aggregation
• Agents: Specialized conductor and analyst agents in agents/ that orchestrate the interview flow

Interview Modules

The interview spans 12 modules plus a screening/demographic preamble (SD). Modules cover dimensions such as formality and register, emotional tone, sentence structure, vocabulary preferences, rhetorical patterns, audience awareness, and stylistic identity. Each module contains 4-8 questions with a mix of question types (likert, forced_choice, scenario, open_ended, writing_sample, calibration, etc.) to triangulate self-reported preferences against observed behavior.

Starting an Interview

1. Generate a UUID session ID.
2. Create the session directory at ~/.human-voice/sessions/{session_id}/.
3. Initialize state.json with status init, empty response arrays, and module progress tracking.
4. Load the question bank from the project's question-bank/modules/ directory.
5. Begin with the screening/demographic module (SD) to establish baseline writer type and branching path.
6. Progress through modules in sequence, applying branching rules and format rotation to maintain engagement.

Resuming an Interview

1. List session directories under ~/.human-voice/sessions/.
2. Identify sessions with status paused or in_progress in their state.json.
3. Load the selected session's state, including the last answered question, current module, and accumulated responses.
4. Resume from the next unanswered question, preserving all prior scoring and branching decisions.

Profile Output

Voice produces a dual-output voice profile stored as profile.json in the session directory:

• Self-Report Layer: Direct preference scores derived from likert, forced_choice, and semantic_differential responses. These capture what the participant believes about their own voice.
• Computational Analysis Layer: Scores derived from NLP analysis of open_ended, writing_sample, and process_narration responses. These capture what the participant actually does in practice.
• Calibration: Calibration questions cross-reference self-report against behavioral signals to produce a calibration delta — the gap between perceived and actual style. High deltas flag dimensions where the participant's self-image diverges from their practice.

The final profile includes per-dimension scores, a composite writer-type classification, distinctive features, and calibration annotations.

Data Directory

All profiles, sessions, and config live under ~/.human-voice/. This is the single canonical location — the plugin does not honour plugin-runtime data directories, ensuring consistent profile access across multiple Claude accounts.

Session Storage

All session data is stored under ~/.human-voice/sessions/{session_id}/:

• state.json — Session state: status, current module, current question index, branching path, timestamps
• responses.json — Raw responses keyed by question_id with timestamps
• scores.json — Running dimension scores updated after each response
• profile.json — Final assembled voice profile (written on completion)
• writing_samples/ — Collected writing samples for NLP analysis