| name | voice-extractor |
| description | Reads the indexed raw corpus and turns it into the atomic unit of a run: voice evidence cards, each with verbatim kept separate from interpretation, one confidence label, and a diffusing flag when a phrase lives in both user voice and creator voice. Also writes the forward voice map of what the market wants you to say. Triggers on: extract evidence cards, build voice map, mine the verbatim, turn sources into cards, what does my market actually say, separate quotes from interpretation, voice extraction. |
Voice Extractor
the extraction engine. it reads raw/ plus 01-source-index.md and produces the two artifacts the rest of the run depends on: the evidence cards (the atomic, traceable unit) and the forward-looking voice map.
the core discipline: never smooth the market's words into your own. verbatim is the market's exact language, untouched. interpretation is your reading of it, in a separate field. if you cannot quote it, it is not an evidence card. this single separation is what keeps the kit from becoming another VOC summarizer that flattens "double-books room 3" into "scheduling concerns."
When to use
use when an indexed corpus exists (raw/ and 01-source-index.md present) and the operator needs evidence cards plus a voice map. invocable standalone or as Stage 2 of frontrun.
do not use to map objections (objection-mapper), score angles (angle-synthesizer), or ingest sources (source-intake).
Inputs
-> 01-source-index.md (the source rows and their reliability)
-> raw/ (the excerpt files every card must trace to)
-> the scope from 00-intake.md (market, business type, audience) for theme judgment
Procedure
1. Read every source
walk raw/ source by source. for each, pull the candidate phrases that carry a tension: a fight, a frustration, a desire, a switch, a status play. flat, neutral, "it works fine" lines are not cards. if there is no tension, there is no card.
2. Write one card per piece of market language
each card conforms to voice-evidence-card.schema.json. the field-by-field guide is in references/extraction-schema.md. the load-bearing fields:
-> verbatim: exact, untouched. copy it, do not clean it. typos and all.
-> interpretation: your reading. separate field. optional, but if present it must never be presented as the market's words.
-> confidence: exactly one of direct_quote / strong_inference / weak_pattern / do_not_use_yet. the rules and examples are in references/evidence-confidence.md.
-> status_flags: add diffusing when the phrase appears in BOTH creator voice and user voice. see the confidence reference.
-> voice_layer: user (what the market feels) or creator (who shapes how the market talks).
-> tension, why_it_matters, do_not_claim: all required, all one line. do_not_claim is the anti-overclaim field: what this evidence does NOT prove.
every card's source_id must resolve to a row in 01-source-index.md that resolves to a file in raw/. a card you cannot trace does not get written.
3. Cluster without flattening
near-identical phrasings cluster, but clustering must not erase the sharpest verbatim. the rubric is in references/voice-cluster-rubric.md. the rule: preserve the sharpest verbatim as the cluster exemplar, count the recurrence, but never replace the exemplar with a smoothed label. "removed CSV export" and "they killed the export button" cluster, but you keep both verbatims and lead with the sharper one.
4. Emit 02-evidence-cards.json
a JSON array of cards. it must validate against the schema: enum fields legal, verbatim/tension/why_it_matters/do_not_claim non-empty, usable_for at least one entry, evidence_id as ev_001 ascending, source_id matching the index.
5. Write 03-voice-map.md (FORWARD)
the forward-looking map: what the market wants you to SAY. organize into:
-> desires: what they are actually trying to get (the outcome, in their words)
-> myths: what they wrongly believe about the category or the product
-> enemy beliefs: the specific wrong thing worth attacking (feeds the angle slate's enemy_belief)
-> buying language: the words they use when they are close to a decision
-> emotional language: the charged, un-inventable phrasing a copywriter would not dare make up
every entry in the voice map cites the evidence_ids behind it. no broad label without the verbatim that proves it.
hold the boundary: the voice map is FORWARD (what to say). objections, anxieties, workarounds, and trust gaps belong in 04-objection-map.md (what to answer), which objection-mapper owns. never write the same cluster into both.
Outputs
| File | What it carries |
|---|
02-evidence-cards.json | the atomic unit. array of cards validating against voice-evidence-card.schema.json. everything downstream cites these. |
03-voice-map.md | FORWARD: desires, myths, enemy beliefs, buying language, emotional language. every entry cites evidence_ids. |
References
references/extraction-schema.md: the card field-by-field guide in prose, mirroring the JSON schema.references/evidence-confidence.md: the four confidence labels plus the diffusing flag, when each applies, with examples.references/voice-cluster-rubric.md: how to cluster near-identical phrasings without flattening, and the user-voice vs creator-voice extraction differences.
