Unfamiliar-user validation (1.0) — run kit

Status: executable kit prepared in 0.9.8; cohort who/when remains owner judgement (pre_release_roadmap_1_0.md §20)
Programme: pre_release_roadmap_1_0.md §14
Related: manual_acceptance_1_0.md, release_severity_triage_1_0.md, known_limitations.md

The 1.0 success criterion centres on an unfamiliar user. Run during indicative 0.9.x hardening / pre-RC once install and principal journeys are stable enough to evaluate. Do not execute this round as part of the 0.9.8 code cut — this file prepares the kit so the round can run without inventing protocol.

Prepared evidence ≠ measured evidence ≠ signed-off evidence.

1. Mandatory protocol (summary)

  • Two to five people who have not developed TranscriptX

  • At least one relatively non-technical user

  • Fresh machine or fresh environment

  • No live coaching unless they become completely blocked (see §6)

  • Record: installation time; time to first useful result; blockers; misunderstood terminology; abandoned journeys

2. Cohort slots (owner fills who/when)

Slot

Role

Eligibility

Who (owner)

When

Consent on file

1

Non-technical

No TranscriptX development; limited CLI comfort OK

[ ]

2

Thoughtful generalist

Has used similar tools; not a maintainer

[ ]

3

Optional

Researcher / analyst emerging audience

[ ]

4

Optional

[ ]

5

Optional

[ ]

Eligibility criteria

  • Has not authored TranscriptX code or release docs

  • Can use a browser; may or may not know Docker/Python

  • Agrees to privacy-safe participation (§5)

  • Uses only synthetic / demo / consented sample transcripts — no private personal recordings unless the participant owns them and consents in writing

Environment requirements

  • Fresh machine or fresh disposable data root + clean install path from install_verification_matrix.md

  • Prefer Docker Compose for predictability; native only if claiming native support

  • Record OS, architecture, install profile, package version, SHA

Curated sample stack (optional facilitator prep)

For a disposable UI that only mounts the facilitator sample set (not the maintainer library), use the sibling tree ../transcriptx_test/ and:

# Once per fresh data tree (or after wiping data/): write the epoch-1 marker
python -c "from pathlib import Path; from transcriptx.core.utils.schema_epoch import write_epoch; write_epoch(Path('../transcriptx_test/data'))"
docker compose -f docker-compose.unfamiliar-user.yml up -d transcriptx-web
# Register pre-copied managed transcripts (Home uses the slug index, not raw disk scan)
docker compose -f docker-compose.unfamiliar-user.yml exec -T transcriptx-web python - <<'PY'
from transcriptx.core.utils.file_discovery import discover_managed_transcript_paths
from transcriptx.io.admit_and_register import _try_register
for p in discover_managed_transcript_paths():
    print(_try_register(p), p.name)
PY

Then open http://127.0.0.1:8502 (port 8502 so it does not collide with the main stack on 8501). This compose file is standalone (does not merge docker-compose.override.yml). Defaults point at transcriptx_test_transcripts / transcriptx_test_recordings / transcriptx_test_outputs plus disposable data/, config/, and transcript-inbox/ under that tree. The data root needs schema_epoch.json (epoch 1) once Streamlit has written any content under it — otherwise the schema-epoch gate blocks analysis. Files copied into the transcripts mount still need registration into .transcriptx_index.json (under outputs) for Home to list them; Library pickers can also see on-disk JSON. See docker.md.

3. Facilitator script (principal journey)

Goal path: install → first useful result → export. Timing starts at first install instruction.

  1. Hand participant the README / website landing (or printed quickstart). Do not narrate steps.

  2. Ask them to install and open the UI.

  3. Ask them to import a provided sample transcript (facilitator-supplied file; no in-app demo pack).

  4. Ask them to run an analysis and find something useful in Overview / Insights / Charts.

  5. Ask them to export or download results.

  6. Optional: explore Settings / advanced pages — only if time remains and no distress.

Permitted facilitator prompts (examples)

  • “What are you trying to do right now?”

  • “Where are you looking for that?”

  • “You can stop whenever you want.”

  • Restate the high-level goal once if forgotten (“install, then get a useful result”).

Forbidden coaching

  • Pointing at specific buttons/menus

  • Dictating install commands beyond what public docs already show on their screen

  • Explaining product jargon unprompted

  • Fixing errors for them (except emergency intervention §6)

Log every intervention (coaching invalidates blockage and time-to-first-result evidence for that segment).

4. Timing sheet

Participant

Install start

UI up

First import

First useful result

Export done

Abandoned?

Notes

Definitions:

  • Install time: start of install instructions → UI reachable

  • Time to first useful result: UI up → participant affirms a useful insight/chart/summary (their words)

5. Privacy-safe participation

  • Informed consent: purpose, voluntary nature, what is recorded, retention, withdrawal

  • Minimal recording: prefer written observation notes; screen/audio only with explicit consent

  • Anonymisation: participant codes (P1…); no real names in shared evidence

  • Avoid private transcript content: use demo/synthetic samples; if personal data appears, stop (§7)

  • Secure retention: raw notes in .local/ scratch; accepted evidence under release-evidence tied to SHA

  • Withdrawal / deletion: honour requests; delete identifiable raw recordings promptly

Consent checklist (per participant):

  • Purpose explained

  • Recording scope agreed

  • Withdrawal explained

  • Sample data provenance explained

6. Emergency intervention rules

Intervene immediately (and log) if:

  • Participant is distressed

  • Privacy concern / personal data exposure risk

  • Unsafe deletion risk (about to wipe non-disposable data)

  • Unrecoverable installation failure after reasonable self-attempts

  • Exposure of personal data in UI/logs

After emergency intervention, mark timing metrics for that segment as invalidated by coaching/intervention.

7. Stop conditions

Stop the session (or that journey) when any of:

  • Distress

  • Privacy concern

  • Unsafe deletion risk

  • Unrecoverable installation failure

  • Exposure of personal data

Record stop reason and severity.

8. Observation form (per finding)

Field

Value

participant code

journey step

install / import / analyse / understand / export / other

observation

quote (optional, anonymised)

blockage?

yes / no

terminology confusion

intervention logged?

yes / no / n/a

9. Severity worksheet → RC gate

Map each issue to release_severity_triage_1_0.md:

Finding ID

Summary

Severity

Blocks RC?

U-001

release blocker / must fix / known limitation / post-1.0

yes if blocker or must-fix

Rule: any release blocker or must-fix from this round explicitly prevents RC entry until fixed or reclassified with owner sign-off.

10. Post-session triage procedure

  1. Consolidate observation forms + timing sheet within 24h.

  2. Deduplicate findings; assign severities.

  3. Copy accepted evidence to release-evidence location for the tested SHA (not only .local/).

  4. Open or update issues for blocker / must-fix items.

  5. Update programme checklist: unfamiliar-user validation evidence reviewed.

  6. Known limitations / post-1.0 items → document; do not silently drop.

11. Triage reminder

Map findings to release_severity_triage_1_0.md. Blockers and must-fix items from this round gate RC.