docs(project): plan live quiz correlated responses

[rschlaefli]

Tracker

ClickUp: https://app.clickup.com/t/86cabym7a

What This Adds

This PR adds a project plan for live quiz correlated response exports.

1. Captures the agreed product decisions from the planning/grill discussion.
2. Maps the current standard live quiz, assessment, temporary pseudonym, and export paths.
3. Defines implementation slices for schema, manage UI, PWA notice, response persistence, temporary respondent alignment, export matrix, and verification.

Important Details

• Assessment remains separate: identifiable response tracing stays mandatory there.
• Standard live quizzes default to the current aggregate-only behavior.
• Correlated export mode is planned as an opt-in setting for future quizzes only.
• Exported response matrices should use stable random respondent labels and avoid names, emails, account ids, usernames, temporary pseudonyms, and respondent type.
• Research / differential-privacy export work is deferred to a later admin workflow.

Branch Coverage

• Base: origin/v3
• Head: f5030a4f12
• Reviewed: 1 commit, 1 added plan file, 404 inserted lines.
• Covered: project/2026-06-20-live-quiz-correlated-responses-plan.md

Review Focus

• Check whether the proposed LiveQuizRespondent shape should replace TemporaryLeaderboardEntry immediately or through a compatibility bridge.
• Check the LiveQuizResponse identity model before implementation touches assessment corrections.
• Check participant notice wording for clarity without over-explaining.

Verification

Current head:

• git diff --name-status origin/v3...HEAD -> one added plan file.
• git diff --stat origin/v3...HEAD -> 1 file changed, 404 insertions.

Not run:

• Automated tests -> not run; docs-only planning PR.

Security / Privacy

• Review: plan identifies privacy-sensitive implementation risks but changes no runtime code.
• Sensitive data: no secrets, credentials, tokens, PII, or private payloads included.

Blocking Before Merge

None for the planning artifact.

Follow-Up After Merge

• Run independent plan review and update the plan with accepted findings.
• Start implementation on the planned slices, beginning with schema and response mode wiring.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c85ed5ba-98fb-42f5-a57e-9402df92e917

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

Docs-only change adding two planning artifacts; no runtime code is touched and no data or schema is altered.

Both files are documentation only. The plan was carefully updated after the first Greptile review, and the new review document verifies every codebase claim with file:line citations. The single remaining gap (Next Steps not sequencing the review-document integration before Slice 1) is a plan-quality note, not a merge blocker.

project/2026-06-20-live-quiz-correlated-responses-plan.md — the Next Steps section should be updated to sequence the review document integration (Findings 1 and 2) before Slice 1 begins.

Important Files Changed

Filename	Overview
project/2026-06-20-live-quiz-correlated-responses-plan.md	Implementation plan for correlated response export; updated to integrate first Greptile review. Migration note (lines 125-131) still describes partial unique indexes that the co-added review document (Finding 2) identifies as unnecessary and risky. Next Steps (lines 421-426) direct an agent to start Slice 1 immediately without first applying the two review-document blockers.
project/2026-07-06-live-quiz-correlated-responses-plan-review.md	Thorough Slice 0 independent review; all codebase evidence claims verified with file:line citations. Findings are actionable with junior-executable instructions and a clear ordered roadmap. No issues found in the review document itself.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Participant submits response in PWA] --> B{Quiz responseCollectionMode?}
    B -->|AGGREGATED_ANONYMOUS default| C[response-api: fire-and-forget Hatchet event]
    B -->|CORRELATED_EXPORT| D[response-api: sync dedup gate Redis vote-hash check]
    D -->|already recorded| E[HTTP 208 recorded-before to client]
    D -->|new response| F[Hatchet event + respondent token]
    C --> G[Standard worker: Redis aggregate only no durable LiveQuizResponse]
    F --> H[Correlated worker branch: verify respondent secret+quizId findUnique dedup gate]
    H -->|duplicate| I[silent first-wins drop]
    H -->|new| J[write LiveQuizResponse respondentId OR participantId]
    J --> K[Redis aggregate updated in parallel]
    G --> L[Block deactivation: flush Redis to ElementInstance.anonymousResults]
    K --> L
    J --> M[(LiveQuizResponse rows per correlated respondent)]
    M --> N[Slice 6: Export matrix respondent_001..N labels HMAC-ordered quiz-scoped salt]
    N --> O{Delivery path - Finding 1 unresolved}
    O -->|Option A| P[CLI admin export + manage-UI note to lecturer]
    O -->|Option B| Q[GraphQL endpoint + manage-UI download button]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Participant submits response in PWA] --> B{Quiz responseCollectionMode?}
    B -->|AGGREGATED_ANONYMOUS default| C[response-api: fire-and-forget Hatchet event]
    B -->|CORRELATED_EXPORT| D[response-api: sync dedup gate Redis vote-hash check]
    D -->|already recorded| E[HTTP 208 recorded-before to client]
    D -->|new response| F[Hatchet event + respondent token]
    C --> G[Standard worker: Redis aggregate only no durable LiveQuizResponse]
    F --> H[Correlated worker branch: verify respondent secret+quizId findUnique dedup gate]
    H -->|duplicate| I[silent first-wins drop]
    H -->|new| J[write LiveQuizResponse respondentId OR participantId]
    J --> K[Redis aggregate updated in parallel]
    G --> L[Block deactivation: flush Redis to ElementInstance.anonymousResults]
    K --> L
    J --> M[(LiveQuizResponse rows per correlated respondent)]
    M --> N[Slice 6: Export matrix respondent_001..N labels HMAC-ordered quiz-scoped salt]
    N --> O{Delivery path - Finding 1 unresolved}
    O -->|Option A| P[CLI admin export + manage-UI note to lecturer]
    O -->|Option B| Q[GraphQL endpoint + manage-UI download button]

Loading

_{Reviews (3): Last reviewed commit: "docs(project): add correlated responses ..." | Re-trigger Greptile}

[rschlaefli]

Independent plan review (Slice 0) pushed as project/2026-07-06-live-quiz-correlated-responses-plan-review.md — all plan claims verified against the codebase with file:line evidence.

Two blockers to resolve on the plan before Slice 1:

1. Export never reaches the lecturer — @klicker-uzh/export is CLI-only with zero app wiring; a lecturer can enable correlated mode but can never download the matrix. Decide delivery (admin workflow vs manage-UI download slice).
2. Migration can be simpler — two ordinary @@unique constraints replace the planned partial unique indexes (Postgres NULLS DISTINCT); only the CHECK needs raw SQL. No partial-index precedent exists in the 175 migrations, and Prisma would fight undeclared indexes.

Also covered: the "recorded-before" duplicate reply needs a new sync gate in response-api (standard path is fire-and-forget today), the publish-lock must be server-side (no existing lock pattern in the wizard), respondent label ordering needs a spec (recommend per-quiz HMAC salt), the still-open nullable verificationSecretHash CHECK, notice copy fixes + DE drafts, deletion/cascade semantics, and an ordered 9-step roadmap a junior can execute.