Internal working note — UI/UX workshop
Coding interviews with several positioned readers, and keeping where they disagree.
MASSHINE codes interview transcripts with more than one positioned reader and records where they read the same passage differently. It does not try to settle on a single agreed codebook. In reflexive thematic analysis, that disagreement is part of the data.
What follows is a description of what is built so far — the idea, the main design decisions, the engine, and the current interface thinking. The first corpus is early-20th-century immigration oral histories, but the engine is not tied to that material.
The idea
Agreement is the usual target. Here it isn't.
Most computer-assisted coding tools, including the recent LLM ones, aim for agreement — a match against a human gold standard, an inter-rater score, one tidy codebook. That assumes there is a single correct reading to converge on.
Reflexive thematic analysis does not assume that. Two researchers with different theoretical commitments will read the same transcript differently, and the difference is itself something to look at. MASSHINE follows that line: it records divergence and ties it to the evidence rather than averaging it away.
So the working surface is meant to read like a workbench rather than a pipeline — read the transcript, ask for a positioned reading, compare readings, write. The machinery (runs, prompts, the sentence index) stays in the background and is there when you want to check it.
Design decisions
The decisions that carry weight.
Each one trades efficiency against fidelity somewhere. The working rule is to take efficiency where it costs nothing and avoid it where it would flatten the reading.
1Index, don't regenerate
The model returns sentence IDs, not retyped text; verbatim spans are resolved from the index. Made-up source text is not possible, and a code with no valid evidence is dropped.
2Reconcile means de-duplicate
The reconcile step only collapses re-wordings of the same point. Grouping codes into themes is a later, separate step, so reconcile doesn't quietly turn into theming.
3Stable code IDs
A counter mints IDs that are never reused or renumbered. C0042 stays the same code as the corpus grows, so themes, decisions and the interface keep pointing at the right thing.
4Independent positioned readers
Divergence comes from declared standpoints reading the same text blind, not from one model reviewing another. Each standpoint is grounded in actual scholarship, so the disagreement can be defended.
5The lens points; the data answers
A standpoint decides where to look, not what to find. With evidence-grounding and a rule to stay quiet where it has nothing to say, a reader doesn't end up stamping its vocabulary on every line.
6Engine and domain pack are separate
The engine is corpus-agnostic. The study-specific parts — vocabulary, method, the standpoint roster, language — live in a swappable pack. A new field is a new pack, not new engine code.
7One mechanical layer
A spaCy sentence index is the only deterministic preprocessing. The analytic "idea unit" is an instruction in the prompt, not a fixed object built in advance.
8Default sampling, reasoning on
The model's temperature is left alone and its reasoning is kept on. That costs latency, which is accepted and made cheap to iterate against by caching.
9Themes are built across interviews
The theme pass reads one transcript at a time against the themes so far. A theme becomes cross-case only when a later interview supports it, and a claim's scope can't outrun the interviews behind it — so the output never reads more general than the evidence.
The engine
How a transcript moves through the pipeline.
FastAPI, SQLite and spaCy. Each stage is a function; the model-facing stages are plain text-prompt files (shown in full further down). The model writes and judges; counting, joining, coverage and ID assignment are ordinary code. The theme pass runs one interview at a time — it reads that transcript against the themes built so far — so a theme's reach grows only as later interviews actually support it. Coding and each theme step are checkpointed, so a run that stalls resumes where it stopped instead of starting over.
Documents are added one at a time: add_document() codes only the new transcript and folds its codes into the existing codebook, keeping the IDs. The whole codebook fits in a prompt up to roughly 10–20 transcripts; past that, a retrieval step (designed, not yet built) selects candidates for reconcile — as retrieval only, with the merge decision left to the model.
A plain-Markdown record of a real two-interview run — sections, codes, the project codebook, and themes — is in engine/exports/md/ (the standard single coder; the three-reader panel produces a parallel set with per-lens codes, sentence-level friction, and provenance themes). The barebones view of the same pipeline this page describes.
Divergence
Two ways the readers diverged on one interview.
On the GRANDE interview, the panel was the standard coder plus a critical / political-economy lens and a phenomenological / memory lens. The two lenses produced fewer codes than the standard coder — 135 / 72 / 99 in one run, 134 / 77 / 89 in another. They stay quiet where they have little to say, and the run-to-run spread is the variance the design sets out to record rather than hide. (These are raw per-lens counts from one GRANDE run; the engine now de-duplicates near-restatements within each lens before counting, so fresh totals run lower, and the theme pass spans both interviews.)
Same evidence, different reading
On "I believe the name of it was America": the standard coder reads a ship's name, the critical lens reads post-war shipping, and the phenomenological lens reads the hesitation "I believe" as uncertain memory.
One reader sees what another skips
On "there was a manure pile just to the side of it": the standard coder left it uncoded; the critical lens read a production unit, the phenomenological lens read the domestic world.
Themes carry their provenance
| Candidate theme | Provenance | |
|---|---|---|
| Work is remembered through the body, and its physical cost falls on the worker rather than employers or the state. | standard 15 · critical 14 · phenom 8 | convergent |
| The ethnic network — prior migrants, kin, a trade passed mother to daughter — is the real infrastructure of settlement. | critical 16 · standard 15 · phenom 6 | critical |
| The account works through stock phrases and silences around the unsayable — a peasant-class way of telling. | phenom 26 · standard 9 · critical 0 | phenom. |
The critical lens produced nothing for the themes about the child's longing for her father or about the narrative silences — the affect-and-memory material its prompt tells it to leave to others. The gap is recorded as it is.
Workbench
The interface, as a working mockup.
The screen below is a working mockup, not a finished product; it is there to give the workshop something concrete to argue with. The reader stays close to the transcript — codes are inline, attached to sentences, and clickable — and the run details (metadata, prompt versions, the log) sit in an audit drawer rather than in the foreground.
It carries the real run: the comparison view shows the three readers side by side, the themes carry provenance, and the codebook holds real codes. The views:
- Reading — transcript with inline codes; co-pilot, autopilot and split modes; a panel to ask a lens about a passage.
- Codebook — each code with its definition, evidence and the lens that produced it.
- Standpoint friction — the same sentence read by the three lenses, side by side.
- Themes — claims with their provenance and the count of preserved tensions.
- Connections / audit — sentences sharing codes, and the run detail behind any suggestion.
For the workshop: how much should friction be ranked or curated; whether a low-loading reference lens should be shown as a baseline; whether the unit stays the sentence or moves to arbitrary spans.
Prompts
The analytic logic, in full.
The prompts are where the method lives. They are read straight from the files, so what you see here is what the engine runs.
Loading…