Lumotia/docs/release/tester-onboarding-kit.md

name, type, tags, description

name	type	tags	description
tester-onboarding-kit	release	release v0.1 testers onboarding email-template feedback	Recruitment email template, platform targets, day-3 check-in script, and feedback-collection protocol for the Lumotia v0.1 private beta (~20 testers).

Tester onboarding kit

Inviting a tester

Paste this into Gmail. Fill in the three variables. Send from your personal address, not a mailing list.

Subject: Lumotia v0.1 — would you try it for me?

Hi {{NAME}},

I'm shipping v0.1 of Lumotia, a local-first dictation + task-capture desktop app.
Local-first means everything runs on your device. No cloud, no telemetry.

Would you install it on your {{PLATFORM}} and try the 10-step getting-started?
Should take 10–15 minutes.

Download: {{DOWNLOAD_URL}}
First-install warnings (SmartScreen / Gatekeeper): https://github.com/jakeadriansames/lumotia/blob/main/docs/release/install-warnings.md
What to do at each step: docs/release/tester-acceptance-runbook.md in the repo

What I'm looking for:
- Did anything confuse you?
- Did anything break?
- Did the cleanup and task extraction make sense?
- Would you use it again next week?

Reply with a few sentences when you're done. No form, no survey.

Thanks,
Jake

Variables:

• {{NAME}} — first name
• {{PLATFORM}} — "Linux", "macOS (Apple Silicon)", or "Windows 11"
• {{DOWNLOAD_URL}} — direct link to the platform artefact from the GitHub release

How many testers, on which platforms

Target: 20 testers across three platforms. Bias toward Linux — it is the primary platform, bugs surface fastest, and iteration is quickest.

Platform	Target count	Priority
Linux (Fedora or Ubuntu)	8–10	Primary — recruit first
macOS Apple Silicon	5–7	Best-effort — needed for RB-08 verification
Windows 11	3–5	Best-effort

For week 1 of private beta, 5–7 testers total across all platforms is realistic. The public-launch metric (20 strangers, post-tag) is separate.

When recruiting, prefer people who:

• Actually dictate or take notes for work
• Are comfortable with "this is pre-release software"
• Will reply honestly if something breaks (not just go quiet)

Avoid recruiting anyone who will feel obligated to say it's great.

Day-3 check-in (if no reply)

Send this if a tester hasn't replied after three days:

Hi {{NAME}},

Just checking in on the Lumotia install. If you got stuck or something broke,
tell me what you saw — that is the most useful feedback I can get right now.

If you didn't get a chance to try it, no worries. Let me know and I'll follow
up later or remove you from the list.

Jake

Do not send a second nudge after this. Silence after two messages means the install failed silently or life happened.

Feedback collection

Routing replies. Every reply goes into one of two places:

1. Real bug or confusing UX — add to docs/release/v0.1-known-limitations.md under "Reporting issues" or open a GitHub issue.
2. Deferred or unclear — add to a private scratch file (docs/private/v0.1.1-deferred-notes.md, not committed). Do not let it sit in your inbox.

After the first five replies: identify the three most common stumbling points and add workarounds to docs/release/v0.1-known-limitations.md. This is a required metric (see v0.1-checklist.md "Support burden signal").

Activation log. Ask testers who are comfortable to optionally share their activation log after three days of use: Settings → Privacy → Activation log. They paste the table into their reply. This is fully local and opt-in — never require it.

Target state. At least 70% of issues should be self-service (tester can describe what went wrong without a call). If you drop below 50%, improve docs and the diagnostic bundle flow before recruiting more testers.

Once a tester replies

When a tester sends a reply that includes an activation log or a diagnostic bundle, use the parser scripts to extract actionable information in under a minute.

Parsing an activation log

Testers paste their activation log table from Settings → Privacy → Activation log. Save the pasted content to a file and run:

python3 scripts/parse-activation-log.py path/to/tester-activation.json

Or if they pasted a plain table (not JSON), pipe it through --paste:

pbpaste | python3 scripts/parse-activation-log.py --paste   # macOS
xclip -o | python3 scripts/parse-activation-log.py --paste  # Linux

The script prints a one-screen summary covering all five activation metrics:

• Activation — was first capture within 3 min of opening the app?
• Core value — did they get ≥ 3 useful captures in the first 24 hours?
• Retention — did they return within 7 days?
• Quality — did extracted tasks get accepted/edited? (? — follow up qualitatively)
• Trust — can they articulate what stays local? (? — follow up qualitatively)

Items marked ? are not in the activation log. Follow up with a direct question per the tester acceptance runbook.

Parsing a diagnostic bundle

Testers who hit a reproducible bug can use Settings → About → Save diagnostic bundle to generate a .zip. They attach it to their reply. Run:

./scripts/parse-diagnostic-bundle.sh path/to/tester-bundle.zip

The script:

1. Checks the bundle passed the redaction deny-list (no audio, no transcripts, no .db files). A FAIL verdict means the bundler has a bug — do not share the bundle further.
2. Prints a content inventory, log error summary (top 3 patterns), and the non-secret preference values.
3. Exits non-zero if any check fails, so it can be piped into a CI-style workflow.

Both scripts require no installation beyond Python 3 (stdlib only) and unzip + jq (for the shell script; jq falls back to grep-based extraction if missing).