AP History essay use case

# AP History essay use case

A single, reusable AP-history-essay AssignmentType covering both essay types on the AP US, European, and World History exams: the **Document-Based Question (DBQ)** and the **Long Essay Question (LEQ)**. Both are graded against College Board rubrics that share the same four-row structure (thesis, contextualization, evidence, analysis & reasoning); they differ in document use, point total, and exam timing. Rather than two AssignmentTypes, one AssignmentType with `essayType: dbq | leq` keeps teacher navigation simple, the prompt library shared, and the tutor/GA framework reused — distinct rubric branches and authoring affordances live inside the one AssignmentType.

## Current status

Draft `yawp-2.0` PR #115 is open as a spec prototype and is stacked on teacher dashboard PR #108. It should stay in design until the dashboard/AssignmentType surface is stable and Brian has had a chance to review the student-facing implications.

The prototype is wireframe-only — every surface uses mock data; nothing persists. It exists to feel the shape of the v1 product and surface UX decisions that bend the spec. Five surfaces are clickable end-to-end:

- AssignmentType detail page (`/app/assignment-types/preview-ap-history-essay`) — hero, teacher directions, submissions section, prompt library
- DBQ/LEQ Builder (`/builder`) — structured editor with prompt + period + time mode + source list
- Student drafting surface (`/draft`) — DBQ two-mode (reading + writing with citation chips); LEQ single-pane with context bank
- Teacher grading view (`/grade`) — College Board rubric panel with mock GA output, calibration drawer, column-wise mode, blind toggle

A companion engineering-facing v1 spec lives in `yawp-2.0` at [`docs/plans/2026-05-09-ap-history-essay-spec-v1.md`](https://github.com/The-Connell-School/yawp-2.0/blob/claude/ap-history-spec-v1-6DaqG/docs/plans/2026-05-09-ap-history-essay-spec-v1.md). This PM doc remains the source of truth for problem/goals/non-goals/UX prose; the engineering doc is the source of truth for schema, file paths, rollout sequencing.

The connecting thread is AP history essay reasoning: defensible thesis with a line of reasoning, contextualization, evidence-as-argument (not summary), and complexity. Distinct from Yawp's thesis-driven essay default in that the rubric is the College Board's, not Yawp's.

## Problem

DBQ + LEQ together account for **40% of every AP history exam** (DBQ 25%, LEQ 15%); with SAQs added, writing is roughly 60% of the score. A student who can write clean DBQ and LEQ essays has a path to a 4 or 5; a student who can't rarely scores above a 3. Both are structurally distinct from anything else students write — defensible thesis with a line of reasoning, contextualization, evidence-as-argument, and complexity, on tight clocks (DBQ 60 min, LEQ 40 min). The DBQ adds 5–7 primary sources to analyze and a sourcing requirement; the LEQ replaces those with outside historical knowledge alone. Two related gaps Yawp doesn't currently serve:

- **Teachers.** Authoring AP essays today happens in Google Docs or Word; assigning means pasting prompts (and for DBQs, source sets) into a course shell; grading against the College Board's rubrics is slow and inconsistent across sections. Teachers running multiple AP sections (the UA professor with 150+ students is the canonical case) can't grade at the cadence the AP exam demands. Several already use third-party AI graders (GradeWithAI, CoGrader, EssayGrader, Class Companion) for volume — Yawp's GA needs to slot into or replace that workflow.
- **Students.** Between graded essays students either don't practice or use generic chatbots that don't know the rubric, the source set, or the named anti-patterns. There's no scaffolded surface that knows what a DBQ or LEQ *is* and coaches accordingly. The pedagogical sequence that consistently moves students from a 2–3 to a 5–6 (diagnose → drill individual rubric moves in isolation → reintegrate into full essays → polish) requires structured tooling no general writing app provides.

An AP History essay AssignmentType slots into the same row as Daily Pages and Narrative Essay: one teacher view, one student drafting surface, rubrics tuned to each essay type, tutor and grading-assistant aware of which type is in play — and on top, a shared prompt library (filterable by essay type), narrowed-scope coaching for per-rubric-move practice, and a teacher grading workflow built around how AP readers actually score.

## Goals (rough)

- One AP History essay AssignmentType, reusable across AP USH / AP Euro / AP World, covering both **DBQ** and **LEQ**. Essay type is a property of each prompt/assignment (`essayType: dbq | leq`); period is too. Tutor, GA, builder, and library all branch on essay type internally.
- Teacher authoring is **its own flow**, not a generic "new assignment" form. AP essays carry too much structured payload (prompt + period + reasoning skill + rubric branch, plus for DBQs 5–7 sources with attributions) for a one-pane form. The "New" button on the AssignmentType detail page matches the existing AssignmentType pattern — a Document/Assignment dropdown, each with a DBQ/LEQ submenu. From there, three start paths land on the structured **Builder**: (1) clicking a row in the always-visible **Prompt Library** section pre-fills the assignment form, (2) **uploading a PDF** of an existing DBQ or LEQ in the Builder lets Yawp parse it, (3) starting from scratch in the Builder. The DBQ path includes source-set parsing/upload; the LEQ path doesn't.
- PDF upload is first-class. Teachers have stacks of College Board released DBQs/LEQs, prep-book essays, and department-shared PDFs. Re-typing a 7-source DBQ into a form is a non-starter — the upload path has to be the *fastest* way to get a real essay into Yawp.
- Tutor flow tuned to genre-specific phases. DBQ: source analysis → thesis → contextualization → drafting → revision. LEQ: thesis → contextualization → drafting → revision (no source analysis; outside evidence carries the entire weight of evidence). Different shape than narrative essay's idea/angle → memory → scene → revise.
- **Tutor framing is "point-hunting," not "write a great essay."** Both rubrics are additive, finite, and nameable. Errors don't subtract. The pedagogically reliable framing — and the one that actually moves students from 3s to 6s — is "execute these specific moves under time pressure," not holistic essay quality. The tutor speaks in this register.
- **Drills as narrowed tutor coaching scopes**, not a separate product surface. Same Document-with-tutor surface as every other Yawp AssignmentType — a "thesis drill" is an AP essay assignment where the tutor's coaching scope is narrowed to thesis quality and the student writes one or a handful of theses. Preserves Yawp's platform shape (tutor + writer) while supporting the "isolate and drill" middle phase of the standard tutoring sequence. Most coaching scopes work for both essay types; doc-analysis and sourcing are DBQ-only.
- Rubrics per the College Board: 7-point DBQ rubric and 6-point LEQ rubric (see below). Both share the same four-row structure (thesis / contextualization / evidence / analysis & reasoning); they differ in evidence and sourcing rows.
- **Calibration samples bundled with each essay.** Every published essay (library or teacher-authored) ships with three sample student essays at high/medium/low scores, mirroring the College Board's 1A/1B/1C release format. The GA uses them as anchors; teachers reference them before grading; students see them after submitting.
- Used by teachers and students alike: same AssignmentType powers teacher authoring/grading and student drafting/practice. Students can also spin up ungraded practice from a published library prompt.

## Non-goals

- **Not a curriculum product.** Yawp doesn't ship a unit/lesson plan around AP history essays. The library seeds prompts (and for DBQs, source sets) — it doesn't sequence them into a course.
- **Not SAQ scaffolding.** SAQs (short-answer questions) live elsewhere on the AP exam and have a different shape; if we tackle them, it's a separate AssignmentType.
- **Not auto-grading.** Teachers stay in the loop; the GA produces a rubric-aligned draft grade and feedback, the teacher confirms or overrides per point.
- **Not AI-branded in the UI** (per platform rule). The tutor presents as a calm coach.

## Rubrics

Both rubrics share the same four-row structure (Thesis / Contextualization / Evidence / Analysis & Reasoning) with identical Thesis, Contextualization, and Complexity definitions. They diverge in the Evidence and Sourcing rows. Source: [College Board AP History rubrics](https://apcentral.collegeboard.org/) (links to specific PDFs attach with engineering handoff).

**Philosophy (applies to both).** The rubric is **additive**: each point is earned independently. Errors don't subtract — exam essays are graded as "first drafts," and minor grammatical or factual mistakes don't cost points unless they obscure meaning or undermine the argument. The play is **point coverage**, not perfection. The GA reflects this — a clunky essay that hits each rubric move plainly outscores a beautifully written one that doesn't.

### DBQ rubric (7 points)

| Category | Points | What "earns the point" looks like |
|---|---:|---|
| Thesis / Claim | 1 | Historically defensible claim that establishes a **line of reasoning** — not a restatement of the prompt and not "yes things changed." Either gives a reason for the position or names analytic categories the body will address. May appear in intro or conclusion but must be in one place. |
| Contextualization | 1 | Broader historical context — what came before, alongside, or after — described with **enough specificity that the reader sees how it sets up the prompt**. Must be more than a passing reference or a phrase. "It was a turbulent time" earns nothing. |
| Evidence — Document Use I | 1 | **Describes** content of at least 3 documents tied to the prompt. Quoting alone doesn't count; the student has to say what the document says. |
| Evidence — Document Use II | 1 | Uses at least 4 documents to **support an argument** — documents as evidence for a claim, not summarized in the order presented. The 4 docs can split across sub-arguments or counterarguments. The named anti-pattern, "walking through the documents," earns the first point but not the second. |
| Evidence — Outside Evidence | 1 | At least one **specific** piece of historical evidence beyond the documents (a named law, person, court case, event), inside the prompt's date window. |
| Analysis & Reasoning — Sourcing | 1 | For at least **2 documents**, explains *how or why* the source's POV, purpose, historical situation, or audience is relevant to the argument. Mnemonic: **HIPP** (Historical situation, Intended audience, Purpose, Point of view). |
| Analysis & Reasoning — Complexity | 1 | Sophisticated argumentation. Three reliable paths: **(1) Qualification** ("while X dominated, Y persisted"), **(2) Multiple causation / multiple perspectives**, **(3) Connection across periods**. The hardest point on the rubric. |
| **Total** | **7** | |

### LEQ rubric (6 points)

| Category | Points | What "earns the point" looks like |
|---|---:|---|
| Thesis / Claim | 1 | Same as DBQ — defensible claim with a line of reasoning. |
| Contextualization | 1 | Same as DBQ — specific historical context, more than a phrase. |
| Evidence I | 1 | Provides at least **two specific examples** of historical evidence relevant to the prompt's topic. |
| Evidence II | 1 | Uses at least **two specific pieces of evidence to support an argument** in response to the prompt — evidence-as-argument, not list-of-facts. |
| Analysis & Reasoning — Historical reasoning | 1 | Uses one of the four reasoning processes (causation, comparison, continuity-and-change, periodization) to **frame or structure** the argument. Surface-level reasoning doesn't earn it; the structure of the argument has to reflect the reasoning skill. |
| Analysis & Reasoning — Complexity | 1 | Same three reliable paths as DBQ. Hardest point on the rubric. |
| **Total** | **6** | |

**Key differences from DBQ.** No Sourcing row (no documents to source). Single Evidence row instead of two — but evidence has to come from outside knowledge, since there are no documents. This makes the **outside-evidence anchors / context bank** even more critical for LEQ than DBQ: it's not one rubric point, it's the entire evidence side of the essay. Strategy implication for LEQ: students rely on memorized period-specific evidence almost exclusively.

A 4 (3 of 6 on LEQ, 3 of 7 on DBQ) is roughly the floor for a passing AP score; a 5 is the target for top scorers. About 74% of APUSH test-takers earned a 3+ in 2025.

The rubric is **tutor-internal**: students don't see the categories or point boxes as a panel during drafting. The tutor speaks in the rubric's vocabulary ("you're using the documents but haven't sourced any of them yet," "your thesis restates the prompt — what's your line of reasoning?") without naming categories. The rubric *does* become visible after submission, on the GA's feedback panel — "make the rubric visible" is one of the most reliable single moves for student improvement, and metacognitive rubric awareness is the actual transferable skill.

### GA tuning rules

The grading assistant should reflect how AP readers actually grade. From the College Board's published guidance:

- **Be generous on grammar and prose quality.** Doesn't matter unless it obscures meaning.
- **Be generous on minor factual errors that don't undermine the argument.** A fuzzy date is fine; "Hoover was a Democrat" in an argument about parties is not.
- **Be strict on describe-vs-argue.** This is where most students lose Evidence II. Hold the line.
- **Be strict on HIPP relevance.** Identification without "...which matters because" doesn't earn sourcing.
- **Be strict on outside-evidence specificity.** Named facts only.
- **Flag period-bleed.** Outside evidence outside the prompt's window doesn't earn the point. (For APUSH this means anything outside 1754–1980; per-prompt windows are tighter.)
- **Don't reward length.** A short tightly argued essay earns complexity; a long repetitive one usually doesn't.

## Tutor flow

Phases in **soft sequence** — same shape as the narrative-essay tutor: the tutor recommends what to do next, the student can skip ahead or jump back, the tutor decides when to suggest moving on based on what's on the page. No hard gates. The phase set branches on essay type.

The tutor opens both essay types by **decoding the prompt**: identifying the historical reasoning skill. AP history essays use four reasoning types — **causation** (causes/effects), **comparison** (similarities/differences), **continuity and change over time**, and **periodization**. The verb tells you which. The tutor surfaces the detected reasoning skill and tailors coaching accordingly (e.g., for change-over-time prompts the tutor pushes on the "while/although" qualification structure; for causation it pushes on multiple causation).

**DBQ phases (5):**

1. **Source analysis.** Tutor walks the student through documents one or two at a time. For each: "What is the document arguing or showing? Which side of the argument does it support? Which HIPP element matters most here, and why does that matter?" Output: a working understanding of each source plus a working group: which 2–3 thematic clusters the documents fall into, mapping to body paragraphs.
2. **Thesis.** Tutor pushes from "the prompt asks about X" to a defensible claim with a line of reasoning. Probes: "what's the counterargument?", "what would someone who disagrees say?" Surfaces a tested template for change-over-time prompts: *"Although [position 1 with nuance], the period from [year] to [year] was characterized primarily by [main argument], driven by [reason 1], [reason 2], and [reason 3]."* That single sentence locks in the line of reasoning AND signals the body-paragraph categories.
3. **Contextualization.** Tutor pushes for 2–3 sentences of specific historical setup, drawing from the period context bank (see Outside-Evidence Anchors below). Coaches against generic-context phrases ("It was a turbulent time" earns nothing) by demanding a specific arc.
4. **Drafting.** Student writes; tutor reacts in rubric vocabulary. Coaches on per-paragraph structure: topic sentence naming a thesis category, 2–3 documents woven together (not one-paragraph-per-doc), at least one HIPP-explained source per body paragraph, outside evidence somewhere, tie-back to thesis at paragraph close.
5. **Revision.** Whole-essay pass. Tutor pushes hardest on complexity — the hardest rubric point. Surfaces the three reliable complexity moves (qualification, multiple causation, connection across periods). Sourcing gaps flagged. Conventions noted but not the focus.

**LEQ phases (4):**

1. **Thesis.** Same as DBQ but the tutor doesn't have documents to lean on — the student arrives with a position from prior knowledge alone, and the tutor pushes them to a defensible claim with a line of reasoning. The change-over-time thesis template applies identically.
2. **Contextualization + evidence brainstorm.** Combined into one phase because LEQ has no document-reading phase to ground the period in. The tutor surfaces the period context bank early and pushes the student to inventory what they know before drafting: "what specific laws, court cases, events, and people from this period could you bring in?" Without this phase students reach the body and run out of evidence.
3. **Drafting.** Student writes; tutor coaches on evidence-as-argument vs. evidence-as-list, the historical-reasoning row (does the structure of the argument actually reflect causation/comparison/CCOT/periodization?), and tie-back to thesis.
4. **Revision.** Same complexity push as DBQ. Historical-reasoning gaps flagged.

Phase progression is suggested in tutor turns, not enforced by the UI.

### Failure-mode detectors

The tutor and GA continuously run a small set of **named anti-pattern detectors** — each one corresponds to a specific way students lose points, drawn from the official sample commentaries:

| Detector | What it catches | Tutor response |
|---|---|---|
| Thesis-restates-prompt | Thesis paraphrases the prompt without a "because/by" clause or analytic categories | "Your thesis names what the prompt asks but not your line of reasoning. What would your *because* clause be?" |
| Walking-through-documents | Body paragraphs structured one-per-document instead of one-per-argument | "Right now you have a paragraph for Doc 1, then Doc 2, then Doc 3. Try grouping these — which two documents make the same argument together?" |
| Description-not-argument | Sentence describes a document's content but doesn't tie it to a claim | "You've said what Document 4 *is*. What does it *do* for your argument?" |
| HIPP-without-relevance | Sourcing identifies POV/audience/purpose/situation but doesn't explain why it matters | "You've named that this is a sermon. Why does that matter for your argument?" |
| Generic-context | Contextualization is a phrase, not a specific arc | "Specific history, not 'a time of change' — what was happening in the decade before?" |
| Generic-outside-evidence | Outside evidence is vague ("many laws were passed") | "Name a specific law, person, or court case." |
| Period-bleed | Outside evidence cited from outside the prompt's date window | "[Reagan's 1980 election] is outside the prompt's 1932–1970 window — that won't earn the outside-evidence point. What from inside the window?" |
| Outside-evidence-from-docs | Outside evidence student named is actually a document subject | "FDR is what Document 1 is about — the outside-evidence point requires evidence the documents don't already mention." |
| Buried-thesis | Draft has no clear thesis sentence at end of ¶1 or in conclusion | "AP readers move fast — the thesis at the end of ¶1 is the safest position. Want to bring it forward?" |
| Length-not-sophistication | Long repetitive draft without complexity move | "Length isn't earning complexity. Try one *while/although* sentence in your conclusion." |

These detectors run as the student writes (lightly, untimed mode) and as the GA scores (always). They map 1:1 to feedback templates the teacher can accept, edit, or override on the grading panel.

### Timed vs. untimed mode

Real exam timing differs by essay type:

- **DBQ: 60 minutes total — 15 reading + 45 writing.** The reading period is the most important 15 minutes; students who plan during it write structured essays, students who skip it write document walk-throughs.
- **LEQ: 40 minutes total, no separate reading phase.** No documents to read; the student writes for the full 40 minutes. (On the AP exam, students choose 1 of 3 LEQ prompts at the start; see open question on prompt-choice modeling.)

**Untimed practice (default).** Tutor coaches deeply through every phase. Student can iterate, jump phases, restart paragraphs.

**Timed practice — phase-structured (DBQ).** Two structurally distinct windows, with on-screen phase markers and a visible clock:

- **Reading phase (15 min).** The document editor is **read-only**. The student can highlight and annotate the prompt and the documents (in-platform highlighter and margin notes), and can write into a planning sidebar (outline, thesis draft, document groupings, outside-evidence brainstorm). They cannot type into the essay body. The tutor is silent unless asked. Phase markers on the clock guide a tested time budget: minutes 0–2 decode prompt, 2–4 brainstorm outside knowledge, 4–14 read documents actively, 14–15 thesis and outline.
- **Writing phase (45 min).** Editor unlocks; planning sidebar stays visible. Tutor remains silent. Soft phase markers suggest target paragraph times (¶1: 5–7 min, ¶2–4: ~8–10 min each, ¶5: 3–5 min, self-check: 2 min) but don't enforce.

**Timed practice — single-phase (LEQ).** A 40-minute writing window with the planning sidebar always available. The tutor is silent. Soft phase markers (decode prompt: 0–2, evidence brainstorm: 2–6, thesis + outline: 6–9, drafting: 9–37, self-check: 37–40) but don't enforce. No reading-period read-only lock since there's nothing to read.

**Submission (both types).** On clock-out or self-submit, the tutor and GA deliver a **retrospective coaching pass**: rubric panel with each point earned/not-earned, named failure-mode flags, suggested edits the student can apply in an "untimed revision" follow-up if the teacher allows. Whether the retrospective shows immediately or waits for grade release is a per-assignment teacher choice.

This is the single highest-leverage feature for serious AP test prep: real exam-condition simulation, with all of Yawp's coaching hidden during the test and unleashed retrospectively. Open question on whether the full phase-structured timed mode lands in v1 or follows; a thinner "clock with no enforcement" is the v0 fallback.

## Drill Mode

The standard tutoring sequence — diagnose → **isolate and drill individual rubric moves** → reintegrate → polish — is the highest-leverage middle phase, and it's the one no general writing app supports. Running full DBQs every session and giving holistic feedback is the single biggest pedagogical mistake; targeted drill on the specific moves a student is missing is what moves them from 3s to 6s.

**Drill Mode is not a separate product surface.** It's the same Document-with-tutor surface every other Yawp AssignmentType uses — the student writes, the tutor coaches as they write — but with the tutor's coaching scope **narrowed to a single rubric move**. A "thesis drill" is an AP essay assignment where `coachingScope = thesis`: the student opens the document, the tutor introduces itself with the focus, the student writes a thesis, the tutor coaches only on thesis quality (defensible → adds line of reasoning → adds qualification), and stops there. Same surface, different tutor focus.

**Coaching scopes** (values on the assignment):

| Scope | Essay types | What the student writes | Documents required? | Tutor focus |
|---|---|---|---|---|
| `full` | DBQ + LEQ | A full essay | DBQ: yes. LEQ: no | All phases. The default. |
| `thesis` | DBQ + LEQ | One thesis sentence (typically 3–5 prompts queued as a batch) | No (prompt only) | Defensible → line of reasoning → qualification. Stops when the thesis hits 7-quality. |
| `contextualization` | DBQ + LEQ | A 3–5 sentence context paragraph | No (prompt only; context bank in the sidebar) | "More than a phrase, specific arc." References the context bank. |
| `evidence` | LEQ-primary | An evidence-as-argument paragraph using 2+ named anchors from the period bank | No | Pushes the student from listing facts to wielding facts as argument. Especially valuable for LEQ where evidence is the whole essay. |
| `doc-analysis` | DBQ-only | A short response per document (content, side, HIPP-with-relevance) | Yes (single document at a time) | Pushes hardest on the "this matters because" sentence. |
| `sourcing` | DBQ-only | A one-sentence HIPP-with-relevance for each of 4 documents | Yes (4 docs from a DBQ) | Strict on relevance, not just identification. |
| `complexity` | DBQ + LEQ | A single complexity sentence per prompt (3–5 prompts) | No (prompt only) | Coaches the three named moves: qualification, multiple causation, connection across periods. |

Each scope produces a short writing exercise — most run 5–15 minutes — that lives in the gradebook as its own artifact, distinct from full-essay submissions (so the dashboard doesn't conflate them; cross-reference Daily Pages dashboard decluttering).

**Diagnostic-driven recommendations.** When a teacher grades a full essay submission (or the GA does), the rubric panel surfaces a one-click "assign focused practice" button that recommends 1–3 narrowed-scope assignments matching the points the student missed. A student with thesis ✓, context ✗, evidence I ✓, evidence II ✗, outside evidence ✗, sourcing ✗, complexity ✗ gets a contextualization drill, a sourcing drill, and a full-essay revision queued — the loop the practitioner literature calls "isolate and drill."

**This is what makes Yawp the curriculum, not just the surface.** A student doing 30 minutes of focused practice twice a week between graded essays is doing what the research says works.

## Outside-Evidence Anchors (period context banks)

Outside evidence is critical to both essay types but more so to LEQ — where it's not one rubric point but the *entire* evidence side of the essay. The platform makes period-specific named anchors a first-class reference, not a thing every student rebuilds from scratch.

**Context bank per testable period.** A short, curated list of 8–15 named items (people, laws, court cases, events, movements) per AP period. Examples for APUSH 1932–1980: New Deal alphabet agencies (CCC, WPA, TVA, AAA, NRA), Social Security Act, Wagner Act, GI Bill, Marshall Plan, Truman's Fair Deal, Brown v. Board, Eisenhower's interstate highway system, JFK's New Frontier, LBJ's Great Society, Medicare/Medicaid, Civil Rights Act, Voting Rights Act, OPEC oil embargo, stagflation, Reagan's 1980 election.

The bank isn't a flashcard quiz — it's a passive reference + an active tutor input. Yawp's pattern is "tutor that gives feedback as you write," not memorization drilling. Students absorb the bank by *using* it during contextualization, evidence brainstorm (LEQ phase 2), and full-essay writing, with the tutor surfacing relevant anchors in coaching turns.

**Where it shows up.**

- **Tutor coaching** references the bank when the student is stuck on outside evidence ("you mentioned the New Deal — Wagner Act and Social Security are documents-adjacent; what about the GI Bill or Marshall Plan as evidence the documents don't cover?").
- **Contextualization drill** opens the bank in the sidebar so the student can pull from it while writing the context paragraph.
- **Student-facing reference tab** in untimed practice. Closed during timed practice. Not editable by students.
- **Teacher contributions** — teachers can add anchors to a school-scoped extension of the bank.

**Period coverage at v1.** APUSH periods 2–8 (1607–1980 — Period 1 and Period 9 aren't tested in DBQ format on APUSH; documenting this explicitly because it constrains library validation too). Euro and World banks come with their respective period launches.

## Calibration samples

Every essay — library or teacher-authored, DBQ or LEQ — can carry **three sample student essays at high (top-band), medium, and low score levels**, mirroring the College Board's 1A/1B/1C release format. Score bands are essay-type-specific (DBQ: 6–7 / 4–5 / 1–3; LEQ: 5–6 / 3–4 / 1–2). The samples are more pedagogically useful than the rubric itself: reading three essays at three score levels on the same prompt is the most efficient way to build calibration, both for the GA and for human teachers.

**Where they're used.**

- **GA anchoring.** When the GA scores a submission, it references the three calibration samples for that essay as in-context anchors. Reduces drift; aligns with how AP readers calibrate at the start of each scoring batch.
- **Teacher pre-grading calibration drawer.** Before a teacher opens a student submission, an inline drawer offers "re-read calibration samples" — the high/medium/low essays for this prompt, with rubric annotations. Mirrors the practitioner advice to anchor with a sample 7 and a sample 4 before a grading batch.
- **Student post-submission learning.** After a student submits (especially after timed practice), the platform surfaces the three samples — "here's what a 6 looks like on this prompt; here's what a 3 looks like." This is one of the most reliable ways to teach the rubric experientially.

**Where they come from.** Library essays ship with curated samples. Teacher-authored essays default to no samples; the teacher can paste their own (e.g., from prior years' student work, anonymized) or skip. v2: the GA can synthesize sample essays at requested score levels for a teacher-authored prompt — useful but lower-priority than getting the curated library samples right.

## AP History Essay Library

Modeled on the Daily Pages prompt library shape. Curated/seeded library of AP history essays — each row carries the prompt, period, era, reasoning skill, rubric-skill emphasis, and (for DBQs) the full source set. The library is the entry point teachers use most often; from-scratch authoring is supported but secondary.

**Default behavior.** New essay assignment opens with an empty form (prompt, period, essay type, etc.). The library is an assist, not a requirement.

**The library.** Browseable, filterable. Click a prompt → New essay assignment form opens with prompt, sources (DBQ only), period, reasoning skill, and rubric pre-filled. Teacher can edit any of it before saving — the library is a starting point, not a locked template.

**Filterable facets (working list):**

- **Essay type** — `DBQ`, `LEQ` (single-select). The most-used filter; defaults to teacher's most recently used.
- **Period** — `AP USH`, `AP Euro`, `AP World` (single-select; default to teacher's most recently used).
- **Era / unit** — period-scoped tag space. For APUSH this maps to the College Board's 9 official periods (II–VIII are testable; I and IX are not). USH eras: "Colonization (1607–1754)," "Revolution (1754–1800)," "Antebellum (1800–1848)," "Civil War & Reconstruction (1844–1877)," "Gilded Age & Progressive Era (1865–1898)," "Imperialism & WWI (1898–1945)," "Postwar & Civil Rights (1945–1980)." Euro and World era taxonomies parallel their respective College Board period frameworks. Multi-value.
- **Reasoning skill** — `causation`, `comparison`, `continuity-and-change`, `periodization`. Single-value, inferred from prompt verb. Drives tutor coaching defaults.
- **Skill emphasis** — which rubric point the prompt is engineered to stretch: `complexity-heavy`, `sourcing-heavy` (DBQ), `contextualization-heavy`, `outside-evidence-heavy` (LEQ-relevant), `balanced`. Multi-value. Available emphases depend on essay type.
- **Source set length** (DBQ-only) — 5, 6, or 7 docs (APUSH released DBQs are always 7). Single-value. Hidden when filtering to LEQ.
- **Source mix** (DBQ-only) — `text-only`, `mixed-media`. Hidden when filtering to LEQ.
- **Difficulty** — `intro`, `mid-year`, `exam-ready`. Single-value, advisory.
- **Free-text search** across prompt body.

**Placement (teacher-only).** The library lives inside the AP History Essay AssignmentType view, and only there. Students never see the library directly — though they may write on a library-sourced prompt their teacher assigned, or in v2 spin up ungraded practice from one.

**UX sketch — the AP History Essay teacher view, top to bottom:**

1. **Header (existing pattern).** Back-to-dashboard breadcrumb, "AP History Essay" title and hero, one-line description, "New ▾" dropdown matching the existing AssignmentType pattern: **Document** and **Assignment**, each with a **DBQ / LEQ** submenu. (Document → DBQ/LEQ opens a fresh student drafting surface; Assignment → DBQ/LEQ opens the Builder for a from-scratch assignment.)
2. **Teacher directions + inspirational examples (new).** Short directions block explaining how AP essays work in Yawp, plus 2–3 *unlinked* example prompt summaries (mix of DBQ and LEQ).
3. **Modules → Submissions dropdown (existing pattern).** Collapsible submissions module, same shape as Daily Pages and other AssignmentTypes. Filter chip inside it for DBQ vs LEQ vs all.
4. **Prompt Library (new).** Mirrors the Daily Pages library shape (`archive/daily-pages-assignments.md` and PR #111). Two-column layout inside a collapsible accordion:
    - **Left: filter sidebar.** Sticky free-text search at the top, then stacked accordion sections — one per facet (Essay type, Period, Era, Reasoning, Difficulty; source-set length and source-mix surface only when Essay type = DBQ). Each section opens to a checkbox list with live counts. AND across facets, OR within a facet.
    - **Right: vertical list of prompt rows.** Count summary + active-filter chips at the top; each row shows a type badge, period · era · source-count metadata, the prompt body in larger type, and reasoning · difficulty · skill-emphasis tags below. No table.
    - **Mobile (< lg).** The filter sidebar collapses into a left-side sheet behind a "Filter" button.
    - The library section defaults *open* on a teacher's first visits and collapses *closed* once they've created their first prompt-from-library.

**Click-through behavior.** Clicking a library prompt opens a **Create Assignment** sheet (slide-in from the right) pre-populated with the prompt body, suggested title, period chip, source-count summary (DBQ-only), and time-mode default. Teacher confirms class/section, time mode, due date, saves. Edits don't write back to the library — the library row stays canonical. The sheet carries an "Open in builder" link for teachers who want fuller editing (reordering sources, swapping the rubric, etc.) before assigning — clicking the link drops them into the Builder with the same prompt pre-filled.

**Sample prompts (shape-only):**

A representative slice across both essay types and all three periods. Full corpus delivers as a sheet attached to engineering handoff.

| ID | Type | Period | Prompt (abridged) | Era | Source Count | Reasoning | Skill Emphasis | Difficulty |
|---|---|---|---|---|---:|---|---|---|
| DBQ-USH-001 | DBQ | AP USH | Evaluate the extent to which the Reconstruction era (1865–1877) marked a turning point in the lives of formerly enslaved people. | Reconstruction | 7 | continuity-and-change | sourcing-heavy, complexity-heavy | mid-year |
| DBQ-USH-002 | DBQ | AP USH | Evaluate the extent to which the Progressive Era reforms (1890–1920) addressed the problems of industrialization. | Progressive Era | 7 | continuity-and-change | balanced | mid-year |
| DBQ-USH-003 | DBQ | AP USH | Evaluate the extent to which the Cold War shaped American domestic policy from 1945 to 1975. | Cold War | 6 | causation | contextualization-heavy | exam-ready |
| LEQ-USH-001 | LEQ | AP USH | Evaluate the relative importance of causes of the American Civil War. | Antebellum | — | causation | outside-evidence-heavy | mid-year |
| LEQ-USH-002 | LEQ | AP USH | Compare the goals and outcomes of Reconstruction policies in the 1860s and 1870s. | Reconstruction | — | comparison | balanced | mid-year |
| LEQ-USH-003 | LEQ | AP USH | Evaluate the extent to which the period from 1945 to 1980 represents a continuation of New Deal liberalism. | Postwar & Civil Rights | — | continuity-and-change | complexity-heavy | exam-ready |
| DBQ-EUR-001 | DBQ | AP Euro | Evaluate the extent to which the Reformation transformed European political authority in the 16th century. | Reformation | 7 | continuity-and-change | complexity-heavy | mid-year |
| LEQ-EUR-001 | LEQ | AP Euro | Compare the responses of European states to the French Revolution. | French Revolution | — | comparison | balanced | mid-year |
| DBQ-WLD-001 | DBQ | AP World | Evaluate the extent to which trans-Saharan trade networks transformed West African societies between 1000 and 1450. | Post-Classical | 5 | continuity-and-change | contextualization-heavy | intro |
| LEQ-WLD-001 | LEQ | AP World | Evaluate the relative importance of factors that drove industrialization between 1750 and 1900. | Industrial | — | causation | outside-evidence-heavy | exam-ready |

**Notes on the schema:**

- `Era`, `Skill Emphasis` are multi-value. `Type`, `Period`, `Source Count`, `Source Mix`, `Reasoning`, `Difficulty` are single-value enums.
- DBQ rows carry the full source set (titles, attributions, bodies, optional images/captions). LEQ rows carry no source set.
- Runtime columns (`Likes`, `Times Used`, `Teacher Rating`, `Student Rating`) seed at zero/blank and live in a separate table joined to the prompt, parallel to Daily Pages.
- Era vocabulary is period-scoped — the era chip filters down based on the selected period.

**Out of scope for v1:**

- Community-contributed prompts. v1 is curated/seeded only.
- Prompt analytics dashboards.
- AI-generated essays on demand. Possible follow-up.
- Upvotes (see v2 below).
- Image-bearing source documents — gated on image support landing (DBQ-only concern).

**v2 — upvote-driven sort.** Same as Daily Pages.

## Domain notes

- New **AssignmentType: AP History Essay**, sitting alongside Daily Pages, Narrative Essay, and the existing thesis-driven default. Inherits the unified Assignment / AssignmentType model from `archive/assignments-unification.md`.
- Each essay assignment holds: `essayType` (`dbq` | `leq`), prompt body, period (USH/Euro/World), reasoning skill (causation/comparison/continuity-and-change/periodization), date window, default time mode, rubric reference (DBQ 7-pt or LEQ 6-pt), and optional calibration samples. DBQ assignments additionally hold an ordered source set (5–7); LEQ assignments don't.
- **Period constraint for APUSH.** AP US History essays always fall within **1754–1980** (DBQs since 2018; LEQs constrain similarly per the College Board's testable-periods guidance). Period 1 (1491–1607) and Period 9 (1980–present) are not tested. Prompt authoring/library validation should enforce this for APUSH; Euro and World have their own per-curriculum windows.
- Period drives historical grounding for the tutor and GA; it's an enum on the *prompt/assignment*, not a separate AssignmentType per period.
- **Coaching scope** is a field on every assignment (`full` | `thesis` | `contextualization` | `evidence` | `doc-analysis` | `sourcing` | `complexity`) that narrows the tutor's focus. `doc-analysis` and `sourcing` are DBQ-only; the rest apply to both essay types. Same Document surface; same Assignment / Submission lifecycle; just a different tutor mode. Diagnostic auto-recommendation produces narrowed-scope assignments based on rubric points missed in a prior full essay.
- Some scopes carry **multiple prompts in one assignment** (e.g., a thesis drill is typically 3–5 prompts queued together). Either model that as a single Assignment with an ordered prompt list, or as a small batch of one-prompt Assignments — open question for engineering. The student-facing flow is the same: open the doc, write a thesis, the tutor coaches, move to the next prompt.
- **Context bank** — a curated reference resource per period; not an Assignment. Teacher and student both read; teachers can extend at the school scope.
- **Feedback snippet** — per-rubric-category templates owned by a teacher (private at v1).
- **Assignment** instances are given to students in a Course as usual.
- Student work happens in a **Document** with DBQ-aware UI (source viewer + scaffolding sidebar from the tutor).
- **Submission** snapshots work as today; teacher grading view gets a 7-point rubric panel populated by the GA.
- Cross-reference [`differentiated-rubrics-by-assignment-type`](differentiated-rubrics-by-assignment-type.md) — the DBQ rubric is the canonical example of a non-default rubric this spec depends on.
- Cross-reference [`daily-pages-assignments`](daily-pages-assignments.md) — the prompt-library shape, schema, and v2 plan should match for consistency.

## UX sketch

To be filled in beyond the AssignmentType view above. Rough shape, by surface:

**Teacher authoring — entry points.** An AP essay carries structured payload (prompt + period + reasoning skill + rubric + time mode, plus DBQ source set) — too much for a one-pane form. Authoring uses the existing AssignmentType pattern (the same "New ▾" dropdown shape Daily Pages and other AssignmentTypes already use), with a DBQ/LEQ branch under each option, plus the always-visible Prompt Library on the page itself as a fourth path:

```
+--------------------------------------------------------------+
| AP History Essay (detail page)                  [Back] [New ▾] |
|                                                              |
|                              ┌─ Document ───▸  DBQ           |
|                    New ▾  ──┤                  LEQ           |
|                              └─ Assignment ─▸  DBQ           |
|                                                LEQ           |
|                                                              |
|  Prompt Library section (filterable, always visible)         |
|  click a row → Create Assignment sheet pre-populated         |
+--------------------------------------------------------------+
```

- **Document → DBQ/LEQ** opens a fresh student drafting surface for the teacher to write on themselves (mirroring how Document works in other AssignmentTypes).
- **Assignment → DBQ/LEQ** opens the Builder with an empty prompt for from-scratch authoring.
- **Library prompt click** opens a Create Assignment sheet pre-populated from the library entry. The sheet has an "Open in builder" escape hatch when fuller editing is needed (reordering DBQ sources, swapping the rubric, etc.).
- **PDF upload** lives inside the Builder itself — a tab/button labeled "Upload PDF" that lets the teacher drop in a College Board release and parse it into the source set. Not a top-level entry path; it's a Builder mode.

All paths that produce an assignment converge into the same **Builder** view — a structured editor where the teacher confirms or edits the prompt, source set, attributions, period, time mode, and rubric before assigning. Library and PDF paths arrive pre-filled; from-scratch arrives empty.

```
+--------------------------------------------------------------+
| DBQ Builder                            [Discard]  [Save]     |
| Prompt                                                       |
|   [textarea, pre-filled if from library/PDF]                 |
| Period: (●) USH  ( ) Euro  ( ) World                         |
| Time mode: (●) Untimed  ( ) Timed (60 min)                   |
|                                                              |
| Sources (1–7)                              [+ add source]    |
|   1. [title] [attribution] [body]      [edit] [↑↓] [x]       |
|   2. [title] [attribution] [body]      [edit] [↑↓] [x]       |
|   ...                                                        |
|                                                              |
| Rubric: [College Board 7-point DBQ ▾]   [preview]            |
| Course / section: [...]   Due: [...]                         |
| [ Save as draft ]   [ Save & assign ]                        |
+--------------------------------------------------------------+
```

### PDF upload path

The fastest path for the realistic teacher case (already-printed DBQ in hand). Steps:

1. **Upload.** Teacher drops in a PDF — College Board released DBQ, prep book scan, department-shared file.
2. **Parse.** Yawp extracts the prompt and the source set, splitting documents at their numbered/lettered headers ("Document 1," "Document A," etc.) and capturing each source's body and attribution line. Period is inferred when possible (USH/Euro/World) from prompt content; teacher confirms.
3. **Review.** Parsed result shows in the DBQ Builder, with each source as an editable card and a side-by-side view of the original PDF page so the teacher can verify nothing was missed or merged. Anything ambiguous (illegible scan, merged sources, missing attribution) is flagged inline with a "needs your eyes" pill on that card.
4. **Confirm and save.** Teacher fixes anything wrong, sets period/time mode, saves. From here the assignment behaves identically to one built from scratch or from the library.

**Realistic failure modes the review step has to absorb:**

- Scanned PDFs with OCR errors — teacher sees the original side-by-side and corrects.
- Image-bearing sources (maps, political cartoons) — until image support lands, parser extracts the caption/attribution and flags the source as image-only; teacher decides whether to skip, replace with a textual proxy, or wait for image support.
- DBQs with non-standard formatting (no numbered docs, prose-embedded sources) — parser does its best, flags low-confidence; teacher can fall back to a "split this manually" mode.
- Multiple DBQs in one PDF (a packet of released exams) — parser detects multiple prompts and asks the teacher which one(s) to import; can create several drafts in one upload.

**Out of scope for v1 of the PDF path:** image extraction, LaTeX/math handling (irrelevant for AP history), and re-uploading the same PDF as a "merge" with edits — re-upload starts a fresh draft.

**Student drafting (DBQ).** Document display is the central UX problem for DBQs — 7 documents alongside an editor and a coach is too much screen real estate to show everything at once. The shape that fits the rubric pedagogy is a **two-mode layout** that mirrors the AP exam itself: deep reading first, fast reference while writing.

**Reading mode** — docs are the canvas.

```
+--------------------------------------------------------------+
| Reading mode — DBQ                              [Coach ▸]    |
| +-----------+ +-----------------------------+ +------------+ |
| | Doc rail  | | Document viewer             | | Planning   | |
| | D1 ●●●    | | Doc 3 — "Letter from..."    | | sidebar    | |
| | D2 ●      | |                             | |            | |
| | D3 ●●  ▸  | | [full text, highlightable]  | | Thesis:    | |
| | D4        | |                             | | Outline:   | |
| | D5 ●      | | margin notes ──> [...]      | | Groupings: | |
| | D6        | |                             | | Outside    | |
| | D7 ●●     | |                             | |  evidence: | |
| | [pin]     | |                             | |            | |
| +-----------+ +-----------------------------+ +------------+ |
+--------------------------------------------------------------+
```

- Left rail: numbered chip per document. Dots indicate annotation count. Pin icon lets the student keep one doc open while opening another (the **"pin two" affordance** — at minimum two docs side-by-side for cross-doc analysis).
- Center: full text of the active doc, with in-platform highlighter and margin notes. This is where most of the reading time goes.
- Right: planning sidebar — outline, thesis draft, document groupings (drag docs into thematic clusters), outside-evidence brainstorm. The artifacts the student carries into writing.
- Coach (top-right toggle): silent during timed mode reading phase; available on demand in untimed.

**Writing mode** — editor is the canvas.

```
+--------------------------------------------------------------+
| Writing mode — DBQ                          [Coach ▸] [Plan ▸] |
| +---+ +-------------------------------------------------+    |
| | D | |                                                 |    |
| | 1 | | Essay editor — student writes here              |    |
| | 2 | |                                                 |    |
| | 3 | | "...as illustrated in [D3], by the 1970s..."    |    |
| | 4 | |             ─────                               |    |
| | 5 | |       hover citation chip expands → [D3 panel]  |    |
| | 6 | |                                                 |    |
| | 7 | |                                                 |    |
| +---+ +-------------------------------------------------+    |
+--------------------------------------------------------------+
```

- Left rail collapses to a thin numbered strip (D1–D7). Each chip shows annotation count from reading mode.
- Click any number → that doc expands as an overlay panel (or inline-anchored panel) over the editor. Click again or click another → swap. Pin two for side-by-side.
- **Citation chips inside the editor.** When the student types `Document 3`, `Doc 3`, or `[D3]`, the editor recognizes the reference and converts it to an inline chip. **Hover** the chip → the doc's content appears in a hover panel. **Click** → the doc opens in the source panel. This is the writing-time superpower: the editor itself becomes the doc-navigation surface, so the source rail can stay thin and most lookups happen inline. Also has a side benefit — the chip count surfaces "you've cited 3 of 7 docs so far" passively to the student, without the rubric panel being visible.
- Annotations and highlights from reading mode persist on each doc; visible whenever the doc is opened during writing.
- Planning sidebar is collapsible (default closed in writing mode, but the student can pull it back out anytime).

**Mode switching.** In **untimed practice**, the student can flip between reading and writing modes freely (top-right toggle). In **timed practice**, the modes are clock-bound: reading mode for the first 15 minutes (editor locked), writing mode auto-engages at minute 15 (planning sidebar persists, editor unlocks). The student can still open docs during the writing phase — they just can't write during reading.

**LEQ student drafting.** No documents → no doc rail, no two-mode split, no citation chips. The Document surface is just editor + planning sidebar (with the period context bank pinnable from the sidebar) + collapsible coach. Closer to a standard Yawp essay shape, lighter than DBQ.

**Teacher grading (Submission view).** The grading workflow is built around how AP readers actually grade, not how Yawp's general grading panel works. Three modes:

- **Single-essay mode (default).** Submission view adds a 7-point rubric panel. Each point shows GA's draft state (earned / not earned), a one-sentence justification, and inline-linked evidence in the draft (e.g., the sentence where the GA flagged sourcing). Teacher confirms or overrides per point; total tallies live. Each rubric category has a feedback bank (see below) the teacher can pull a snippet from.
- **Column-wise mode (new).** When the teacher has a class set to grade, they can switch to a "grade by category across all essays" view: read every essay's thesis first and score every thesis, then every essay's context, etc. This produces dramatically more consistent rubric application than essay-by-essay grading because the teacher is comparing apples to apples. Practitioner literature treats this as the gold-standard calibration practice for class-set DBQ grading.
- **Calibration drawer.** Inline pull-out before grading any essay (or before opening column-wise mode): the high/medium/low calibration samples for this DBQ (see Calibration Samples above), so the teacher recalibrates "what a 6 looks like" before scoring.

**Feedback snippet bank.** Most rubric-aligned teacher feedback repeats. The grading panel surfaces a per-category snippet bank — pre-seeded with high-utility templates ("Your thesis named one cause but didn't establish a line of reasoning — try adding a 'because' clause," "You identified the source's POV but didn't explain its relevance — add 'which matters because...'"), extensible by the teacher. Snippets are scoped to teacher (private) at v1; school-scoped sharing is a v2 add. Saves hours and improves consistency.

**Blind grading toggle.** Optional class-set toggle that hides student names during grading to reduce halo bias. Especially valuable on subjective rubric points like complexity. Off by default.

**Errors-don't-subtract enforcement.** The GA suppresses grammar/typo flags and minor factual error flags from the rubric scoring path entirely, surfacing them only as advisory notes the teacher can review separately. This keeps the rubric clean — point coverage, not perfection.

State transitions, button labels, empty/loading/timed states — to be detailed.

## Data model implications

To be detailed in design pass. Starting list:

- `AssignmentType.kind = 'dbq'` (or discriminator field) with DBQ-specific payload: source set, period, default time mode, rubric reference.
- `DbqSource` table or JSON column on the AssignmentType: ordered list with `title`, `attribution`, `body`, optional `caption`, optional image.
- `DbqDraft` (or equivalent) for in-progress builder sessions, especially PDF-parsed drafts that aren't yet confirmed. Holds the parsed payload, original PDF reference, and per-source confidence flags. Discarded on save-or-cancel.
- Original uploaded PDFs need a storage location (S3 or equivalent) — kept around at least through assignment lifetime so the side-by-side review view works for re-edits.
- `Assignment.timeMode` enum (`untimed` | `timed`) — overridable per assignment instance.
- `DbqCalibrationSample` table or JSON: tied to an AssignmentType row, holds three samples (high/mid/low) with score and rubric-point annotations. Used by GA at scoring time and surfaced in teacher/student calibration drawers.
- `Drill` table: `kind`, `sourceDbqId` (optional), `studentId`, `output`, `tutorFeedback`, `completedAt`. Drills are short and high-frequency — index for fast student-side listing.
- `ContextBank` table: per period, ordered list of anchor entries (`name`, `category`: person | law | event | court-case | movement, `summary`, `dateOrRange`). Read-only at the global tier; school-scoped extensions live in a separate join table.
- `FeedbackSnippet` table: per teacher, per rubric category, body text. Surfaced in the grading panel snippet picker.
- `TimedSession` table for timed practice runs: phase (`reading` | `writing` | `submitted`), `startedAt`, `phaseTransitionedAt`, `submittedAt`, annotations + planning-sidebar contents persisted alongside the document body. Lets the GA's retrospective coaching pass reason about what the student did during reading vs. writing.
- Rubric stored as structured data (depends on `differentiated-rubrics-by-assignment-type`); DBQ rubric is the canonical 7-point template.
- DBQ Prompt Library: separate table from AssignmentType, joined for runtime stats. Mirrors Daily Pages library schema for consistency.
- **Backward-compat.** Existing AssignmentTypes get `kind = 'standard'` via dual-write/backfill. No destructive migration. Source set and period fields are additive.
- Versioning question: when a teacher edits a DBQ AssignmentType after assignment, do in-flight student documents see the change? See edge cases.

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

Best-guess only — engineering will refine.

- `services/web-app/app/routes/assignment-types/...` (DBQ AssignmentType view, authoring form, library)
- `services/web-app/app/components/document/...` (DBQ-aware drafting surface: source viewer, coach sidebar)
- `services/web-app/app/components/grading/...` (7-point rubric panel)
- `services/web-app/app/components/library/...` (shared library shell with Daily Pages)
- `services/web-app/app/components/dbq-builder/...` (entry-picker, structured editor, side-by-side PDF review)
- `services/web-app/app/routes/upload/...` or new endpoint for PDF intake
- `packages/db/...` (AssignmentType discriminator, DbqSource, DbqDraft, time mode, library table)
- `packages/domain/...` (DBQ-specific business logic, GA rubric scoring)
- `packages/tutor/...` (DBQ phase machine, coaching prompts, failure-mode detectors, reasoning-skill detection from prompt verb)
- `packages/dbq-parser/...` (new) — PDF intake, document splitting, attribution extraction, confidence flags
- `packages/dbq-grader/...` (new or extension of GA) — 7-point rubric scoring, calibration-sample anchoring, errors-don't-subtract enforcement
- (No separate drill components — drills run on the existing Document-with-tutor surface; the tutor reads `coachingScope` from the assignment and adjusts behavior.)
- `services/web-app/app/components/context-bank/...` (period reference, student tab, teacher extension UI)
- `services/web-app/app/components/grading/column-mode/...` (column-wise class-set grading view)
- `services/web-app/app/components/timed-mode/...` (phase markers, reading-only enforcement, planning sidebar)

## Open questions

- [ ] v1 launch scope: all three periods at once, or sequence (USH → Euro → World)? Now leaning **APUSH-first** since the pedagogical material we have (rubric guidance, failure modes, drill sequence, calibration samples, College Board released DBQs) is APUSH-specific. Euro and World need parallel research before they're as well-tuned. (Kevin)
- [ ] Coaching scopes in v1: which to ship beyond `full`? Likely candidates are `thesis` (smallest scope, biggest pedagogical win, no documents required) and `sourcing` (uses the documents from a parent DBQ, so reuses existing infrastructure). The other four follow once we have usage data telling us which matter most. (Kevin)
- [ ] Multi-prompt-per-assignment shape: should a thesis drill carry 3–5 prompts in one assignment, or be a queued batch of single-prompt assignments? Affects gradebook clutter and student flow. (Bryant — engineering preference)
- [ ] Timed mode v1 scope: full phase-structured (reading-only enforcement, planning sidebar, phase markers, retrospective pass), or thinner "60-minute clock with no enforcement" v0? Phase-structured is the high-leverage version but also the bigger build. (Kevin / Bryant)
- [ ] Context bank — who curates the v1 anchors per period? Same authorship question as library prompts; can probably share a sourcing pass. (Kevin)
- [ ] Calibration samples — for library DBQs we can lift College Board's published 1A/1B/1C samples (subject to copyright). For teacher-authored DBQs, do we ship a "GA-synthesized samples" feature in v1, or leave samples optional and add synthesis as v2? (Kevin)
- [ ] Where does "Drill" live in the gradebook? Drills are formative, fast, and high-frequency — they shouldn't clutter the submitted-essays view (cross-reference Daily Pages dashboard decluttering). Probably their own filter/section. (Kevin)
- [ ] Reasoning-skill detection from prompt verb — confidence threshold before the tutor commits to a coaching style? Hedge with "this looks like a continuity-and-change prompt — sound right?" or just decide silently?
- [ ] AP Euro / AP World rubric — same 7-point shape per the College Board, but does the era taxonomy and pedagogical material need a parallel research pass like the APUSH one before those launch? (Kevin)
- [x] Hero image: a cartoon stick figure with a quill — generic-history vibe rather than a named figure, to avoid skewing toward any one period (Euro/USH/World). Same playful energy as the Daily Pages cat. **Resolved:** asset committed alongside the prototype at `yawp-2.0/services/web-app/public/img/AP%20History%20Hero%20Image.png` (intentional exception to the PM-repo "no binaries" rule since it's a UI asset for the live preview). Visible on the dashboard tile and as a wide banner on the AssignmentType detail page.
- [ ] Source documents — text-only at v1, or do we need image support (maps, political cartoons) from day one? Library tags mixed-media regardless so we can flip later. (Bryant — feasibility)
- [ ] Rubric customization: ship the College Board 7-point rubric verbatim, or let teachers tweak per assignment? Probably verbatim at v1. (Kevin)
- [ ] Outside-evidence point (1 pt) is hard to coach in real time — does the tutor probe explicitly ("what else do you know about X?") or only flag at revision? (Kevin)
- [ ] Should students see retrospective tutor commentary after timed practice ends, or wait until grade release? (Kevin)
- [ ] Library seed corpus: who authors the v1 prompts and source sets across all three periods? Teacher-vetted external source for AP-quality DBQs, or in-house authored? (Kevin)
- [ ] Era vocabulary per period — lock the v1 taxonomy or evolve from the seed sheet, parallel to Daily Pages?
- [ ] Practice mode: can a student spin up an ungraded DBQ on their own from a library prompt their teacher hasn't assigned? Or only via assignment? (Kevin)
- [x] Filters compose AND across facets, OR within a facet — **resolved**: confirmed consistent with Daily Pages library (PR #111). Prototype implements the same.
- [ ] PDF parser quality bar for v1: what's the minimum reliable parse rate before the path is ready for teachers? (Bryant — feasibility on parsing College Board PDF formats specifically)
- [ ] Do College Board released DBQs have stable enough formatting to template against, or is every prep-book PDF its own snowflake? (Kevin to share a sample set to Bryant)
- [ ] Copyright/licensing: re-hosting a College Board PDF inside Yawp is fine for one teacher's class, but does it constrain the future library/sharing path? (Kevin)
- [ ] Should the PDF upload also auto-tag period/era/skill emphasis to drop the parsed DBQ into the teacher's personal library, or only the assignment? (Kevin)

## Edge cases

To be enumerated. Initial list:

- Teacher edits a DBQ AssignmentType after it's been assigned — do in-flight student documents see the change, or are they version-locked? (Same question Daily Pages and Narrative Essay raise; resolve consistently across all three.)
- Source document is deleted from a DBQ AssignmentType after assignment — version question again.
- Library prompt is updated by curators after a teacher already pulled it into an assignment — assignment is a copy, library update doesn't propagate (matches Daily Pages).
- Student starts in untimed mode; teacher later flips the assignment to timed — what happens to in-progress drafts?
- Student pastes a full essay from elsewhere — paste alert should fire (cross-reference `bugs/paste-alert-detection-broken.md`).
- Student opens a timed DBQ, runs the clock down, writes nothing — submission state? Grace period?
- Student has the DBQ open across multiple tabs (cross-reference `multi-tab-editing-warning`).
- AP teacher running 5 sections with the same DBQ wants identical timed-window mechanics across sections — bulk-create or duplicate-with-edits flow.
- PDF upload returns a parse the teacher rejects entirely — does the draft hold the PDF for retry, or is it discarded immediately?
- PDF upload contains a DBQ for a period the teacher didn't expect (uploaded a Euro DBQ into an AP USH context) — parser surfaces the mismatch as a flag rather than blocking.
- Image-only source in an uploaded PDF before image support lands — teacher needs an explicit "skip this source" or "replace with text proxy" affordance, not silent omission.
- Two teachers in the same school upload the same College Board PDF — no cross-teacher dedup at v1; each upload creates an independent assignment. Worth revisiting when the school-shared library question gets answered.
- Teacher authors a DBQ with a date window outside APUSH's testable 1754–1980 range (e.g., a Period 1 prompt for use as a non-AP exercise) — soft warning, not a block. The tutor's reasoning-skill and outside-evidence coaching may be less reliable outside the exam-tested range.
- Student in timed mode hits the 15-minute mark with no annotations and no planning notes — the editor unlocks for the writing phase but the tutor flags retrospectively that the reading phase wasn't used.
- Student in timed mode types into the planning sidebar but never advances to the writing phase — submission state? Probably auto-submit at clock-out with whatever's there, scored as best the GA can.
- Drill auto-recommendation produces 5+ drills (student missed most of the rubric) — UI caps at 3 to avoid overwhelming, surfaces the rest as "and more" the student or teacher can expand.
- Student games the failure-mode detectors (e.g., adds a token "while/although" sentence that doesn't actually qualify the argument) — the GA's complexity scoring is the backstop; the detector is advisory, not authoritative.
- Calibration samples carry attribution issues (anonymizing real student work for sharing) — needs a documented anonymization pass before any teacher-authored sample can be shared school-wide.

## Test plan

To be written. Will reference existing test files in `yawp-2.0` once paths firm up.

## Rollout

Feature flag (`dbq_assignment_type`). Default off.

**APUSH-first launch** is the recommended scoping. We have authoritative pedagogical material for APUSH (the 7-point rubric in detail, the named failure modes, the Diagnose → Drill → Reintegrate → Polish sequence, period-specific outside-evidence anchors, calibration samples from College Board released exams). AP Euro and AP World share the rubric structure but need a parallel research pass to seed era taxonomies, context banks, and library prompts at the same depth. Shipping APUSH well beats shipping all three thinly.

**APUSH launch contents (v1):**

- DBQ + LEQ AssignmentType, with the Document/Assignment + DBQ/LEQ "New ▾" dropdown, the always-visible Prompt Library (click-to-pre-populate Create Assignment), the Builder converging from library / PDF / from-scratch, and a student drafting surface with tutor coaching.
- Prompt Library seeded with curated APUSH DBQs across the testable periods.
- Tutor with reasoning-skill detection, the five-phase flow, and the named failure-mode detectors.
- GA scoring against the 7-point rubric with calibration-sample anchoring and errors-don't-subtract enforcement.
- Tutor coaching scopes beyond `full`: at least `thesis` and `sourcing` in v1 (smallest scope + reuses DBQ documents respectively); remaining four follow.
- Context Bank for APUSH testable periods.
- Single-essay grading mode + feedback snippet bank. Column-wise mode and blind grading toggle in v1 if scope allows; otherwise v1.1.
- Phase-structured timed mode in v1 if Bryant's feasibility check confirms; otherwise thinner "60-minute clock" v0 with full version in v1.1.

**AP Euro and AP World launch later** with their own research-backed material, in the same shape.

**Pilot order within APUSH:** UA professor first (highest volume, single course, fastest feedback loop), then Washington and Birmingham City. Big-bang within a school once enabled — teachers need it consistently across sections.

## Engineering handoff checklist

A spec is `ready-for-engineering` only when all of these are true.

- [ ] 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