LEQ assignment screen

# LEQ assignment screen

The student-facing writing surface for a Long Essay Question — the screen a student opens when they sit down to draft an LEQ. The shape matches the standard five-paragraph essay drafting surface exactly; everything that's LEQ-specific lives underneath the UI.

## Scope

**In scope.** The student-facing canvas, controls, and persistence for an LEQ draft. Layout, prompt presentation, tutor sidebar, timed vs. untimed display rules.

**Out of scope** (specified separately):

- LEQ tutor behavior — phase coaching, what the coach says and when. See [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) "Tutor flow" and the future LEQ-tutor sibling spec called out in [`dbq-tutor.md`](dbq-tutor.md).
- LEQ grading assistant — rubric scoring, calibration-sample anchoring. See [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) "GA tuning rules."
- Teacher authoring (Builder, PDF upload, library). See the parent spec.
- DBQ student screen — distinct surface, much heavier. See [`dbq-assignment-screen.md`](dbq-assignment-screen.md).

The parent [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) sketches a starting shape; this spec inherits it and drives it to engineering-ready.

## Problem

There is no LEQ-aware drafting surface in Yawp today. Students who want to practice LEQs either write in Google Docs (no rubric awareness, no genre-specific coaching, no integration with their teacher's gradebook) or use third-party tools that don't speak the College Board's six-point rubric. The student-side gap is part of why Yawp can't yet serve AP history classes.

Unlike DBQ, the LEQ task is structurally close to a standard Yawp essay: a single prompt, no documents, no source viewer, no citation chips. The screen does not need a bespoke shape — what it needs is the rubric, the tutor, and the timed mode wired beneath a familiar canvas.

## Goals

- A drafting surface that feels indistinguishable from any other Yawp essay drafting screen — same prompt-on-top, doc-in-middle, tutor-sidebar layout as the five-paragraph essay shape.
- Calm under exam pressure. No clutter, no AI branding, no distractions during a 40-minute clock.
- Mobile responsiveness consistent with other student-facing surfaces.
- Behavior under timed mode is unambiguous: phase, clock, and constraints are obvious at a glance.

## Non-goals

- Not introducing any LEQ-specific UI element on the student canvas. If a coaching need can be served by the tutor, the tutor serves it.
- Not exposing the period context bank to the student (see "Key decisions" below). The bank is tutor-internal.
- Not a tutor surface — the sidebar is part of this screen, but tutor contents and behavior are specified separately.
- Not a grading surface — no rubric panel here.

## Key decisions

These are the design calls that distinguish this screen from "the standard essay screen" — captured here so the engineering session doesn't have to re-derive them.

1. **Layout matches the five-paragraph essay drafting surface exactly.** Prompt banner across the top, document canvas in the middle, tutor sidebar to the right. No bespoke LEQ chrome. Consistency with the rest of Yawp wins; nothing about the LEQ task requires a different shape.
2. **The period context bank is tutor-internal only.** Students never see the bank as a visible reference, sidebar tab, popover, or anywhere else on this screen. On the actual AP exam, LEQ students get no documents, no notes, no reference list — outside evidence is entirely from memory. If Yawp showed the bank during practice, students would lean on it and miss the point of the LEQ rubric's evidence row. The tutor pulls from the bank when coaching contextualization and evidence phases (per [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) tutor flow), but the bank itself stays behind the curtain.
3. **All LEQ-specific behavior is under the hood.** The rubric (6-point LEQ rubric), the default timed mode (40 minutes, single phase, no reading period), and the tutor's awareness of the period's named anchors are all wired beneath the same UI a five-paragraph essay uses. From the student's view, the only difference from a five-paragraph essay is the prompt content and the rubric the GA eventually grades against.

## Domain notes

- The student is working on a **Document** tied to an **Assignment** whose **AssignmentType.kind = 'ap-history-essay'** with `essayType: leq` (per the parent spec). The AssignmentType carries the prompt, the period, and the time mode default. The Assignment instance may override the time mode.
- **TimedSession** (from the parent spec's data model) tracks phase, transitions, and timestamps for a timed run. For LEQ this is single-phase (writing only); there is no reading-period flip the way DBQ has.
- The Document body persists as today. There are no LEQ-specific draft artifacts (no annotations, no document groupings) — what the student types is what travels into the Submission.
- Submission flow is the same as a standard essay: student submits, the body snapshots into a Submission, the student leaves the screen.
- The period context bank is a tutor input, not a student-visible Document artifact. It belongs to the AssignmentType / period metadata, not to the Document row.

## UX sketch

Identical to the five-paragraph essay drafting surface. Documented here for completeness so engineering doesn't second-guess.

```
┌─────────────────────────────────────────────────────────┬──────────────┐
│ Prompt: Evaluate the extent to which the period from    │              │
│         1945 to 1980 represents a continuation of New   │    Tutor     │
│         Deal liberalism.                                │    sidebar   │
├─────────────────────────────────────────────────────────┤              │
│                                                         │  ┌────────┐  │
│  Your draft                                             │  │ tutor  │  │
│                                                         │  │  turn  │  │
│  The decades after 1945 carried forward the central     │  └────────┘  │
│  bargain of the New Deal even as the political          │              │
│  coalition that produced it began to fracture...        │  ┌────────┐  │
│                                                         │  │  you   │  │
│                                                         │  └────────┘  │
│                                                         │              │
│                                                         │  [reply…]    │
└─────────────────────────────────────────────────────────┴──────────────┘
```

- **Prompt banner.** Same component, same placement, same behavior as on the five-paragraph essay screen. Shows the full prompt; collapses to a one-liner on small viewports.
- **Doc canvas.** Same editor as every other Yawp document. No source rail, no citation chips, no two-mode split.
- **Tutor sidebar.** Same sidebar component, same collapse behavior. Coaching content is LEQ-tuned (see future LEQ-tutor sibling spec) but the chrome is unchanged.
- **Timed mode.** When the Assignment is set to timed, the screen shows a single clock (40 minutes by default) in the same location the five-paragraph essay screen would show its clock. Single phase — no read-only reading period. Soft phase markers (decode prompt, evidence brainstorm, thesis + outline, drafting, self-check) are tutor-side guidance, not screen-side gates.

## Data model implications

No new student-facing schema for this screen specifically — it reuses the existing Document, Assignment, and TimedSession shapes established in the parent spec.

- `Assignment.essayType = 'leq'` (per parent spec) is what tells this screen to render in LEQ mode rather than DBQ mode.
- The period context bank lives on the AssignmentType / period metadata (per parent spec). This screen does **not** read from it directly; the tutor does.

Backward-compat: shipping this screen does not migrate existing data. Existing Documents that aren't tied to an LEQ AssignmentType render exactly as they do today.

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

Best-guess starting list — engineering will refine.

- `services/web-app/app/routes/documents.$id.tsx` (or wherever the standard essay drafting route lives) — branch on `essayType === 'leq'` to load LEQ-specific tutor context and timed-mode defaults.
- `services/web-app/app/components/document-editor/` — likely no changes; the standard editor is reused as-is.
- `services/web-app/app/components/prompt-banner/` — no changes; reused as-is.
- `services/web-app/app/components/tutor-sidebar/` — no chrome changes; LEQ-tuned content lives in the tutor module, not this component.
- `services/web-app/app/lib/timed-session/` — LEQ single-phase timed-session config.

## Edge cases

- **Student switches from untimed to timed mid-draft.** Same behavior as the five-paragraph essay screen; no LEQ-specific handling.
- **Student opens the same LEQ in two tabs.** Cross-reference [`multi-tab-editing-warning.md`](multi-tab-editing-warning.md). LEQ has no annotation state, so this is no worse than any other essay — the standard warning applies.
- **Teacher changes the prompt after a student has started drafting.** Handled by the existing Assignment-edit conventions; not LEQ-specific.
- **Tutor surfaces a context-bank anchor in coaching, student asks "where did you get that?"** Tutor responds in its own voice (e.g., "from what we know about the period"); does not expose the bank as a list. Coaching content for this case lives in the LEQ-tutor spec.
- **Submission released back to the student with grade.** Standard flow; the rubric breakdown the student sees is the 6-point LEQ rubric, not the five-paragraph rubric. The screen here is not the one that displays the grade.

## Test plan

- Unit: route renders the standard layout when `essayType === 'leq'`; no LEQ-specific UI elements present.
- Unit: timed mode for LEQ defaults to 40 minutes, single phase, no reading-period state.
- Integration: tutor sidebar receives the period context bank as an input but does not pass it through to any rendered component.
- E2E: a student can open an LEQ assignment, draft a body, and submit, with no visible difference from drafting a standard essay (aside from prompt content).
- Manual QA: verify the bank does not appear anywhere on the student canvas, sidebar, prompt banner, or timed-mode chrome — including hover states, popovers, and keyboard-accessible disclosures.

## Rollout

Feature flag, scoped to AP-history pilot teachers initially. Default to ON for pilot teachers (UA professor, then Washington, then Birmingham City), per the parent spec's APUSH-first launch.

Because this screen is structurally a reuse of the existing essay drafting surface, the risk surface is small — the flag mostly gates "does the LEQ AssignmentType variant exist for this teacher" rather than "is the new layout safe."

## Open questions

- [ ] Does the prompt-choice convention on the real AP exam (student picks 1 of 3 LEQ prompts at the start) get modeled here, or do teachers always assign a single prompt? Inherited from parent spec's open question; doesn't block this screen, but affects whether the prompt banner ever needs to render a "you chose this one" state. (Kevin)
- [ ] Confirm that the standard editor's word-count behavior is acceptable for LEQ (no hard cap; AP exam doesn't have one either). (Kevin)

## 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