Exemplary paper library

# Exemplary paper library

> **Superseded by [Essay Examples](../features/essay-examples.md) on 2026-05-06.** This file was a parallel draft of the same idea. Merged decisions in the canonical spec: grade-level-only attribution, two-step nomination → consent flow (carried over from this draft), surfaces in **both** the in-context module-page gallery and a dedicated searchable library (this draft's contribution), no upvoting in V1 (V2 backlog), separate `ExemplarNomination` table with state machine (this draft's contribution). Preserved here for the reasoning trail — do not edit.

---

A curated, student-consented library of high-scoring YAWP! essays that teachers can nominate and students can browse — so the platform's own success stories become the model essays students have never had access to.

## Problem

We're asking students to write good essays, but most students have never read many truly good essays in their lives. Textbook examples feel distant and curated by committee. The essays being written on YAWP! right now — at 90%+ — are real, contemporary, student-produced work at the exact level we're asking others to reach. Those exemplars are sitting invisible inside individual teacher gradebooks.

Meanwhile, teachers have no structured way to say "this is what I mean when I say a strong essay." The library closes both gaps: it sources examples from real students on the platform, and it gives teachers and students a shared reference point.

## Goals

- Teachers can nominate any submission scoring 90% or above, at any time after grading.
- When the teacher releases the grade to the student, the student sees a clear, low-pressure consent prompt: would they like their paper to be used as an example for other YAWP! students?
- Consented papers enter the library, attributed as: *"Kevin, an 11th grade YAWP! student"* — first name and grade level only, no school, no last name.
- Students and teachers can browse the library, filtered by grade level and assignment type.
- Students can withdraw consent at any time, which removes the paper from the library.

## Non-goals

- Requiring consent before grade release — students receive their grade and feedback regardless of consent status.
- Displaying school name, last name, teacher name, or any other identifying information beyond first name and grade level.
- Replacing teacher-provided model texts. This supplements, it doesn't replace.
- Public internet access — the library is YAWP!-internal only, visible only to authenticated users.

## UX sketch

**Teacher side — nomination**

On the submission detail view, after a grade of 90%+ is recorded, a "Nominate as exemplar" action appears near the grade. Teacher clicks it; a small confirmation: "This paper will be offered to the student for the exemplary library when you release their grade." Nomination is saved but dormant until grade release.

**Student side — consent prompt at grade release**

When the teacher releases the grade, the student's grade-release screen (or notification) includes a secondary prompt below the grade/feedback:

```
Your teacher thought your essay was exceptional.
Would you like it shared as an example for other YAWP! students?
It would appear as: "Kevin, an 11th grade YAWP! student."

  [ Yes, share it ]   [ No thanks ]
```

No nudging language. Both options are equal weight. Student can change their mind later from their account settings or document view.

**Library view**

A browseable page — probably under a "Learn from others" or "Exemplary essays" tab — showing consented papers. Filters: grade level, assignment type (GA essay, daily pages, etc.). Each card shows the anonymized attribution, the assignment prompt, and the full essay text.

Teachers can also surface specific library papers directly to their class, linking one from the library into an assignment or feedback note.

## Domain notes

- Involves `Submission` (the nominated paper), `Assignment`/`AssignmentType` (for filtering), and a new concept — call it `ExemplarNomination` — that links a submission to a library entry and tracks consent state.
- Consent state machine: `nominated` → `pending_consent` (on grade release) → `consented` or `declined`. From `consented`, student can transition to `withdrawn`.
- The anonymized display name (first name + grade level) must be derived at display time from the student's profile, not stored as a string — so it stays current if a student's grade level updates.

## Data model implications

New table `exemplar_nominations`:
- `submission_id` (FK → submissions)
- `nominated_by` (FK → users, the teacher)
- `nominated_at`
- `consent_state` enum: `nominated`, `pending_consent`, `consented`, `declined`, `withdrawn`
- `consented_at` / `withdrawn_at` (nullable)

Backward-compatible: purely additive. No changes to existing submissions or users tables. Grade release flow gets a new hook to flip `nominated` → `pending_consent` and surface the consent prompt.

## File paths in `yawp-2.0` likely to change

- `packages/db/` — new migration for `exemplar_nominations`
- `services/web-app/app/routes/submissions/` — nomination action on submission detail
- `services/web-app/app/routes/grade-release/` — consent prompt on grade release
- `services/web-app/app/routes/library/` — new library browse route (likely new file)
- `services/web-app/app/components/` — nomination badge, consent modal, library card components

## Open questions

- [ ] Where exactly does the library live in the nav? Under the student's home, teacher's dashboard, or a top-level tab? (Kevin to decide)
- [ ] Can teachers see which of their nominated papers have been consented vs. declined? Or is consent opaque to the teacher to avoid pressure dynamics?
- [ ] What happens to a library entry if a student later contests their grade or the submission is revised under the revision flow?
- [ ] Minimum library size before surfacing to students — do we wait until there are N exemplars before making the library visible, so it doesn't feel empty?
- [ ] Do we want any curation beyond teacher nomination? (e.g., staff can remove entries that don't meet community standards) — probably yes, need a simple admin flag.

## Edge cases

- Student declines consent, then later wants to add it — must be self-service, no teacher intervention required.
- Student withdraws after consenting — paper disappears from library immediately; any teacher-linked references to it should degrade gracefully (show "this example is no longer available").
- Teacher nominates a paper, then adjusts the grade below 90% before release — nomination should be auto-rescinded or at least flagged for the teacher to confirm.
- Student is a minor — consent from the student is a UX gesture; legal parental consent for minors is a real question. One option: default to fully anonymous for all students (grade level only, no first name), which sidesteps the issue entirely and may be the cleaner default regardless. Worth deciding before launch.
- Same student has multiple 90%+ papers — each paper is nominated and consented independently.
- Teacher leaves the platform — their nominations and any consented papers remain; library entries aren't tied to active teacher accounts.

## Test plan

- Unit: consent state machine transitions — all valid paths, all invalid transitions rejected.
- Unit: anonymized attribution renders first name + grade level only, never school or last name.
- Integration: grade release flow triggers consent prompt when a `pending_consent` nomination exists.
- Integration: withdrawal removes paper from library query results immediately.
- E2E: full teacher nomination → grade release → student consent → paper appears in library flow.
- Manual QA: library browse with filters; verify no PII beyond first name + grade level visible anywhere.

## Rollout

Feature flag (`exemplary_library_enabled`). Start with a single pilot teacher at UA — needs a teacher who is actively grading and willing to nominate. Gather a baseline of ~10–20 consented exemplars before opening library browsing to students. Then expand within UA before rolling to Washington and Birmingham City.

## Engineering handoff checklist

- [ ] Domain context covered
- [ ] File paths in `yawp-2.0` listed
- [ ] Data model implications spelled out, including backward-compat plan
- [ ] UX sketch in prose
- [ ] Edge cases enumerated
- [ ] Test plan written
- [ ] Rollout plan decided