Writing competitions

# Writing competitions

A platform-wide layer that turns student writing into something celebratory and aspirational — not just graded. V1 piggybacks on the consented exemplar library to surface "best of" essays as a recognition surface for students and teachers. V2 introduces announced, topic-based competitions that students can opt into and that produce a real winner.

## Problem

Students rarely see writing as something with stakes beyond a grade. The act of writing is private — between them, their teacher, and a rubric. Outside school-run scholarship contests (which most students never enter), there's no mechanism on the platform that says "your writing might matter beyond this assignment."

Teachers, similarly, have no easy way to celebrate exceptional work platform-wide. The best essay in their class lives in their gradebook and disappears.

This is felt by:

- **Students**, who lose motivation when writing feels like compliance. A visible "this could be recognized" pathway raises the ceiling.
- **Teachers**, who want their strongest students to be seen and want a low-effort way to nominate them.
- **Schools and districts** considering Yawp at scale — competitions are a tangible, marketable hook ("our students compete on Yawp!") and a story that resonates in board meetings and parent newsletters.
- **Yawp the product**, which benefits from network-effect surfaces. Competitions create a reason for students across schools to be aware of each other's work.

## Phasing

### V1 — Recognition layer on top of the exemplar library

The simplest version of this is not a competition at all — it's a *spotlight*. Reuse the consented essay pool from [Essay Examples](essay-examples.md) and present it as recognition rather than as study material.

Possible shapes (pick one or two for V1, not all):

- **"Essay of the week / month."** Highlight one consented essay platform-wide on a rotating basis. Could be staff-curated or signal-driven (highest teacher score + student consent in the window).
- **"Top essays" leaderboard.** A public-to-students list of consented exemplars filtered by grade level or assignment type, lightly ranked. Could use the V2 upvoting from `essay-examples.md` once that exists.
- **Teacher's choice spotlight.** Teachers nominate one essay per term as their "pick of the term." Surfaces in a dedicated tab.

V1 adds no new submission surface. Students don't enter anything new — they consent (or have already consented) via the existing exemplar flow, and the platform features their work. Net new lift is mostly UI on top of the existing nomination + consent pipeline.

### V2 — Announced topic-based competitions

A real competition surface. Yawp announces a competition with a topic, a window, and a result.

Open questions about shape:

- **Cadence.** End-of-year only? Quarterly? Monthly? Tied to academic calendar? Unclear — likely fewer, larger competitions beat many small ones for prestige.
- **Topic source.** Yawp staff picks topics? Partnered with an outside organization (literary magazine, school district, university)? Teachers vote? A mix?
- **Entry mechanism.** Does a student write a *new* essay specifically for the competition, or can they submit an already-graded existing essay? Probably both, with a flag.
- **Judging.** Teacher panel? Yawp staff? Outside judges (university faculty, published writers)? AI-assisted shortlist + human final round?
- **Stakes / prizes.** Pure recognition? Cash? Scholarship credit? Featured publication? This is the big unknown — the answer changes the legal, operational, and brand calculus dramatically.
- **Eligibility.** Open to all Yawp students? Limited to certain grade levels or pilot schools at first? Teacher must approve entry?

### Hard rule check (both phases)

- **No AI branding.** A competition surface is exactly the kind of place where an "AI judge" framing would be off-brand and unwise. Judging signals must be human or invisible.
- **Backward-compat.** Both phases sit on top of existing data; no destructive changes.
- **Mobile-responsive.** Competition browsing and entry must work on phones. Students will see competitions linked from social, email, or a teacher's announcement and tap on a phone first.
- **Minor consent / PII.** Same posture as `essay-examples.md`. Public-facing recognition for students under 18 needs legal review; default attribution stays grade-level-only unless a student (and likely guardian) opts up.

## Goals

- Students see writing as something with stakes beyond their grade.
- The strongest student work on the platform is visible *as* strong, not buried in private gradebooks.
- Schools and districts gain a tangible, talkable hook ("our kids compete on Yawp") for outreach and adoption.
- V1 ships with near-zero new infrastructure by reusing the consented exemplar pool.
- V2, when it ships, has a clear cadence, judging model, and prize structure decided up front.

## Non-goals

- Not a replacement for grading or rubrics. Competition signal is celebratory; rubric signal is instructional.
- Not a public, web-indexable showcase outside Yawp (V1 or V2). Recognition surfaces stay logged-in; minor-PII concerns are too live to publish openly without a serious legal pass.
- Not real-time / synchronous (no live writing events). Entries happen async over a window.
- Not a peer-grading mechanism. Students don't judge each other's competition entries.

## Domain notes

V1 reuses:

- `Submission` — the entry, already in the system.
- `ExemplarNomination` (from `essay-examples.md`) — the existing nomination + consent state machine. V1 doesn't need its own.
- `Profile` — for grade-level attribution.

V2 likely adds:

- **Competition** — a thing with a topic, an open/close window, eligibility rules, and a state (`draft`, `open`, `closed`, `judged`, `announced`).
- **CompetitionEntry** — links a `Submission` (or a new submission specifically written for the competition) to a `Competition`. Has its own consent state, possibly distinct from the general exemplar consent (a student might consent to compete but not to be in the exemplar library, or vice versa).
- **CompetitionResult** — winner, finalists, judges' notes if any.

These are a starting list. Engineering will refine in the V2 spec when it splits off.

## UX sketch

### V1: spotlight surface

A new section on the student home (or wherever Examples lives once `essay-examples.md` ships) that highlights recognized essays. Light copy, no leaderboard mechanics.

```
+--------------------------------------------------------------+
| Spotlight                                                    |
| ---                                                          |
| "An 11th grade student on YAWP!" — Featured this month       |
| [excerpt of the essay, ~3 lines]                             |
| [Read the full essay →]                                      |
|                                                              |
| Recently recognized                                          |
| · "A 12th grade student" — thesis essay                      |
| · "A 9th grade student" — narrative essay                    |
| · "An 11th grade student" — analytical essay                 |
+--------------------------------------------------------------+
```

### V2: competition surface

A "Competitions" tab. List of open, upcoming, and past competitions. Each has its own page with topic, deadline, entry rules, eligibility, and (after close) results.

```
+--------------------------------------------------------------+
| Competitions                                                 |
| ---                                                          |
| OPEN: "Write about a turning point" — closes May 30          |
|   Open to: 9–12                                              |
|   [Enter →]                                                  |
|                                                              |
| UPCOMING: "Yawp end-of-year showcase" — opens June 1         |
|                                                              |
| PAST                                                         |
| · "Place" (Spring 2026) — winner announced                   |
| · "First lines" (Winter 2026) — winner announced             |
+--------------------------------------------------------------+
```

Entry flow (V2): student opens a competition page → taps "Enter" → either picks an existing submission they already wrote that fits, or starts a new essay scoped to the competition prompt → confirms competition consent (separate from general exemplar consent) → entry is recorded.

## Open questions

- [ ] **V1 surface placement.** Top-level tab? Inside Examples library? Student home dashboard module? Probably starts as a section inside Examples to avoid net-new nav.
- [ ] **V1 selection model.** Staff-curated, signal-driven (highest scores in the window), or teacher-nominated "spotlight" picks? Or all three with editorial blending?
- [ ] **V2 cadence.** End-of-year only is simplest. Quarterly is more engaging but ~4× the operational lift. Need a call before V2 design begins.
- [ ] **V2 prizes.** Recognition-only, or real stakes (publication, cash, scholarship)? This is the biggest open question — it gates legal, operational, and partnership work.
- [ ] **V2 judging model.** Yawp staff? Teacher panel? Outside literary judges? Hybrid? Decide before scoping.
- [ ] **Topic sourcing.** Internal vs. partnered. Partnerships (e.g., a university English department) add legitimacy but slow announcement cadence.
- [ ] **Entry consent vs. exemplar consent.** Are these the same toggle or distinct? Lean distinct — students may want to compete without their essay living in the public exemplar library.
- [ ] **Teacher-of-record involvement.** Does a student's teacher need to approve their entry? Or is it student-direct? Lean student-direct with optional teacher visibility.
- [ ] **Attribution at announcement.** Default grade-level-only (matches `essay-examples.md`). Winners might opt up to first name + school with guardian consent. Pending legal.
- [ ] **What counts as "winning."** Single winner per competition, or finalists + winner? Recognition for everyone who entered (participation) or only for the top tier?

## Edge cases

V1:

- **No consented essays in the window.** Spotlight surface gracefully shows "no spotlight this month" rather than going stale; or backfills from the broader exemplar pool.
- **Withdrawn after spotlight.** Spotlight unpublishes immediately, same as the exemplar gallery.

V2:

- **Student enters, then withdraws consent before judging.** Entry is removed from the running. Document this clearly in the entry flow.
- **Student enters, then withdraws after winning.** Tricky. Likely allow withdrawal but keep the win recorded internally for the student's account; remove the public surface.
- **Submission edited after entry.** Freeze the entry to the version-at-submission, parallel to the exemplar consent question in `essay-examples.md`.
- **Multiple entries per student.** Allow or limit one per competition? Lean one per competition to keep judging tractable.
- **Cross-school comparisons.** A 9th grader at a pilot school competing against a 12th grader at another. Eligibility rules + grade-level brackets handle most of this.
- **Teachers entering on a student's behalf.** Not allowed — entry must originate from the student.

## Test plan

V1 (lightweight, mostly UI on top of existing flows):

- Spotlight surface renders consented exemplars only. Withdrawn essays disappear.
- Selection model (whichever is chosen) produces deterministic, defensible results given a fixed input pool.
- Empty-state handling.

V2 (full plan to be drafted in a V2-specific spec when this splits off):

- Competition lifecycle state machine: `draft → open → closed → judged → announced`. Invalid transitions rejected.
- Entry creation tied to a real Submission and the active competition window.
- Consent layering: competition entry consent ≠ general exemplar consent.
- Judging surface (whatever shape it takes) doesn't leak unjudged entries.
- E2E: full happy-path entry → close → announce → winner visible to student.

## Rollout

V1: feature flag (`writing_spotlight_enabled`). Default OFF. Enable for UA first once the exemplar pool from `essay-examples.md` has enough consented entries (say, 20+). Expand to Washington and Birmingham City after a month of stable spotlight content.

V2: separate spec when the cadence + prize + judging questions are answered. Will need its own feature flag (`writing_competitions_enabled`), legal review, and likely a partnership conversation before any public announcement.

## Marketing / positioning notes

V1 is mostly internal recognition, but even at V1 it's a story we can tell on the public homepage (see `public-homepage-revamp.md`): "Real students, real essays, recognized on Yawp." V2 is the genuine sales hook — "Yawp Writing Competitions" — and dovetails with district-level outreach.

Don't announce V2 publicly until cadence and prizes are decided. Pre-announcement without follow-through is worse than silence.

## Engineering handoff checklist

V1 only; V2 will get its own checklist when split into its own spec.

- [ ] Domain context covered (V1 reuses `ExemplarNomination`)
- [ ] File paths in `yawp-2.0` listed
- [ ] Data model implications spelled out (V1: none new)
- [ ] UX sketch in prose
- [ ] Edge cases enumerated
- [ ] Test plan written
- [ ] Rollout plan decided