ACT Writing Section

# ACT Writing Section

The ACT Writing essay as a first-class Yawp **AssignmentType**, with a matching tutor and grading assistant, so students can get repeated, timed, rubric-aligned writing practice with immediate feedback. This is the first **test-prep** assignment type and the first half of the standardized-test writing pillar; the SAT Writing section is a sibling follow-on.

## Source

- Split out of [`act-sat-writing-practice.md`](act-sat-writing-practice.md) (the combined ACT/SAT idea), per the decision to build **ACT first** as its own type. SAT remains a follow-on.
- Granola meeting: `3fbd5f2d-e409-42bd-b585-fed305edd5cd`, **Summer priorities — assignment types, LMS integration, and reporter**, 2026-05-26. ACT Writing got the clearest near-term rationale on that call: some schools use ACT Writing as institutional writing data, but students often get ineffective last-minute prep.
- Rolls up under [`summer-build-2026.md`](summer-build-2026.md) Priority 1 (assignment-type expansion), where "ACT writing section" is listed in the test-prep build tier after the AP courses.

## Problem

Schools that lean on the ACT Writing score as institutional writing data need students to get **repeated, timed practice with fast, rubric-aligned feedback** — and teachers rarely have time to assign enough reps and return detailed feedback before test day. Last-minute prep is the norm and it underperforms.

Yawp already has the pieces this needs (an AssignmentType model that resolves a tutor + grading-assistant pair, a timed-session mechanism built for the DBQ, and an essay editor with autosave). What's missing is an ACT-Writing-shaped assignment: a prompt that presents an issue with three perspectives, a coach that knows the specific moves the ACT rewards, and a grader calibrated to the four-domain 2–12 rubric.

## The ACT Writing task (domain primer)

So the spec is unambiguous for engineering:

- **One essay, 40 minutes**, optional section of the ACT.
- The prompt presents a **contemporary, debatable issue** and **three short perspectives** on it.
- The student must: (1) develop and clearly state **their own perspective** on the issue; (2) **analyze the relationship** between their perspective and **at least one** of the three given perspectives; (3) support with reasoning and examples; (4) organize the argument; (5) write in clear, controlled language.
- Scored on **four domains**, each **1–6** per reader, by two readers → **2–12 per domain**, and the four domain scores are averaged to a reported **2–12** Writing score:
  1. **Ideas and Analysis** — clear thesis/perspective; engagement with multiple perspectives; analysis of implications, tensions, and complexity.
  2. **Development and Support** — reasoning and illustration; qualifications; depth, not just assertion.
  3. **Organization** — overall structure, logical grouping, transitions.
  4. **Language Use and Conventions** — word choice, sentence variety, grammar/usage/mechanics **in service of clarity**.

**The single biggest score cap** is the relationship-analysis move in Ideas and Analysis: students routinely state their own view *and* summarize the three perspectives but never analyze how their view *relates to* the others. The tutor and GA both center on that move.

**Key contrast with the DBQ:** there are no source documents to read, group, or cite; there is one timed phase, not a reading-then-writing split; and **conventions count** (Domain 4), so the DBQ's strict "errors don't subtract" posture does **not** carry over. ACT Writing is closer to the LEQ in surface complexity than to the DBQ.

## Goals

- Ship `ACT Writing` as a real AssignmentType selected via the standardized assignment creator, resolving the ACT Writing tutor and ACT Writing GA by default.
- Give students repeatable practice with **immediate, rubric-aligned feedback** against the four ACT domains.
- Support **timed practice** (40-minute default, single phase) reusing the DBQ's `TimedSession`, with an untimed practice mode.
- Tune the tutor to the ACT moves — especially the perspective-relationship analysis — and the GA to the 2–12 four-domain rubric.
- Prepare point value / grade display for gradebook and future LMS compatibility (via [`assignment-creation-standardization.md`](assignment-creation-standardization.md)).

## Non-goals

- Full ACT prep across all sections (English, Math, Reading, Science). This is the Writing essay only.
- Claiming official ACT scoring equivalence before calibration against published sample essays.
- SAT Writing — a sibling follow-on type, not in this spec.
- A bespoke prompt-authoring suite beyond "issue + three perspectives" text fields plus a starter library.
- LMS grade passback itself — this spec only prepares the assignment model for it.

## Domain notes

- The student works on a **Document** tied to an **Assignment** whose **`AssignmentType.kind = 'act_writing'`**. Behavior selection keys off the stable `kind` slug, **not** title matching — per the design bias in [`daily-pages-assignment-type-model.md`](daily-pages-assignment-type-model.md) ("title matching is too fragile for behavior selection").
- `AssignmentType.kind` resolves the **default tutor** (ACT Writing coach) and **default grading assistant** (ACT four-domain GA). This is the same "type determines the tutor/GA pair" contract the standardization spec relies on.
- **ACT Writing prompt content** — the issue statement plus the three perspectives — is the new domain object. It belongs to the **Assignment** (teacher-authored or library-selected), not hardcoded. See data model.
- **TimedSession** (from the DBQ parent spec) tracks `phase` and `startedAt`. ACT Writing uses a **single** `writing` phase with a 40-minute default, versus the DBQ's `reading`→`writing` split. Untimed mode runs with no session clock.
- **Submission** already stores `score`, `rubricScores`, `overallScore`, `numericPercentage`, `letterGrade`, `gradedAt`. The four ACT domain scores go in `rubricScores`; the 2–12 composite in `overallScore`.
- **Feature flags** gate visibility, consistent with [`assignment-type-visibility.md`](assignment-type-visibility.md) (`isSystem`, org-scoped types).

## Data model implications

Mostly additive; reuses existing entities.

- **`AssignmentType.kind`** gains the value `'act_writing'`. If a stable `kind`/slug column does not exist yet, this spec depends on it landing (it is the open ask in [`daily-pages-assignment-type-model.md`](daily-pages-assignment-type-model.md)). Behavior must not branch on `title === "ACT Writing"`.
- **ACT Writing prompt** — the issue + three perspectives. Two options:
  - **A (preferred for v1):** a structured JSON column on `Assignment`, e.g. `actWritingPrompt: { issue: string, perspectives: [{ id, text }] }` with exactly three perspectives. Lowest-friction, no new table.
  - **B:** a dedicated `ActWritingPrompt` table joined to `Assignment`, if prompts need to be a reusable library entity with their own lifecycle. Pick B only if the prompt library (open question) needs first-class prompt rows.
- **`Assignment.submitForGrade` / `Assignment.pointValue`** — inherited from [`assignment-creation-standardization.md`](assignment-creation-standardization.md). Suggested default point value for a major timed essay: `100` (overridable). Submit-for-grade default is an open question for low-stakes reps.
- **`TimedSession`** — reused. ACT config: single `writing` phase, `durationMinutes` default `40`, plus an `untimed` mode. No reading phase.
- **`Submission`** — `rubricScores` holds the four domain scores (each 1–6, or 2–12 if two-reader simulation); `overallScore` holds the 2–12 composite; `numericPercentage` / `letterGrade` derive from the 2–12 → gradebook mapping (open question).
- **`TutorSession` / `DetectorFire`** — reused from the tutor infrastructure (see [`dbq-tutor.md`](dbq-tutor.md) data model). Per-Document, per-student.

**Backward-compat:** all additive. No destructive migration. Existing assignment types and submissions unaffected. New `kind` value and prompt column default empty/null for non-ACT assignments.

## UX sketch

### Student screen

Much thinner than the DBQ — no source documents, no doc rail, no citation chips. Three zones:

```
┌──────────┬──────────────────────────────────────────────────────────────┐
│          │ ⏱ 38:42   Issue: Many public spaces now rely on automation… │
│  Tutor   ├──────────────────────────────┬───────────────────────────────┤
│  chat    │  Perspectives                │   Your essay                  │
│          │  ┌──────────────────────────┐│                               │
│ ┌──────┐ │  │ Perspective One          ││   Automation in public        │
│ │ tutor│ │  │ Automation strips away…  ││   spaces…                     │
│ │ turn │ │  └──────────────────────────┘│                               │
│ └──────┘ │  ┌──────────────────────────┐│                               │
│ ┌──────┐ │  │ Perspective Two          ││                               │
│ │ you  │ │  │ Machines free us to…     ││                               │
│ └──────┘ │  └──────────────────────────┘│                               │
│          │  ┌──────────────────────────┐│                               │
│          │  │ Perspective Three        ││                               │
│ [ask ▸ ] │  │ The trade-off depends…   ││                               │
└──────────┴──┴──────────────────────────┴┴───────────────────────────────┘
```

- **Tutor stripe (left, collapsible).** Same surface contract as the DBQ tutor stripe ([`dbq-assignment-screen.md`](dbq-assignment-screen.md) "Zone 1"): vertical chat, collapsible (default expanded, per-student persisted), input at the bottom, never injects into the editor, no AI branding.
- **Prompt banner (top).** The issue statement, verbatim, always visible. Carries the **timer** when in timed mode.
- **Perspectives panel (middle).** The three given perspectives as three read-only cards, always visible. No annotation taxonomy and no "pin" in v1 — they are short. (A v2 candidate: let the student tag each perspective agree/disagree/qualify to seed the relationship-analysis move.)
- **Essay editor (right).** The standard Yawp editor — autosave, formatting, version history. No citation chips (nothing to cite). Submit affordance matches the existing convention used by other Yawp assignments.
- **Resizable panels + reset layout**, mirroring the DBQ screen, so a student can widen the editor while writing.

### Timed mode

Single phase, simpler than the DBQ's two-phase clock:

- **Writing phase (0–40 min, configurable).** Editor active from the start; perspectives and prompt visible throughout. Visible countdown in the prompt banner.
- **Auto-submit at expiry.** Whatever is in the editor snapshots into a Submission.
- **Resume across tab close** via server-side `TimedSession.startedAt` — never restart the clock (same rule as the DBQ).
- **Untimed practice.** No clock, manual submit only.

### Teacher authoring

Through the standardized assignment creator ([`assignment-creation-standardization.md`](assignment-creation-standardization.md)) — pick `ACT Writing` as the type, then author the **issue** and **three perspectives** (four text fields), set point value, submit-for-grade, due date, timed/untimed + duration, and target classes. v1 may also offer a starter prompt **library** (open question). No teacher-facing tutor-context box (removed by the standardization spec).

## Tutor (ACT Writing coach)

Same architecture as [`dbq-tutor.md`](dbq-tutor.md): a soft-sequence phase machine, named failure-mode detectors, voice rules, a verbatim rubric artifact, and a calibration set. Lives in `packages/tutor/act-writing/`.

### Phase machine (soft sequence; student can skip/jump)

1. **Unpack the issue and perspectives** — make sure the student understands the debate and what each of the three perspectives actually claims.
2. **Stake a position** — the student commits to a clear, defensible perspective of their own (the thesis).
3. **Plan the engagement** — decide which given perspective(s) to engage and *how* (agree / disagree / qualify), and line up the reasoning and examples. **This is where the relationship-analysis move is set up.**
4. **Draft.**
5. **Revise** — verify the relationship analysis is explicit, support is specific, organization holds, and language is controlled.

In timed mode the tutor also **paces** — a light nudge toward drafting if the student is still planning deep into the clock.

### Named failure-mode detectors (starter set — tune against a labeled corpus)

| Detector | Signal | Tutor response (template) | Severity |
|---|---|---|---|
| No clear position | Thesis hedges or never commits | "Where do *you* land? Pick a side you can defend — you can still acknowledge the others." | Blocking before drafting |
| Summary without a stance | Restates the three perspectives, no own view | "You've laid out the three views. What's *yours*?" | Blocking |
| No relationship analysis | Own view present, but never analyzes how it relates to any given perspective | "You've got your position — now connect it. Where does it agree with, build on, or push against Perspective Two?" | Blocking — the #1 score cap |
| Generic support | Assertions with no specific reasoning or example | "Make it concrete. What's one specific example or reason that shows this?" | Soft, persistent |
| Restates the prompt | Thesis echoes the issue statement | "That's the issue, not your take. What do you actually argue about it?" | Soft |
| One-sided / no tension | Never acknowledges a counter-current or complication | "What's the strongest version of the other side? One honest concession makes your analysis stronger." | Soft, surface in revision |
| Five-paragraph padding | Formulaic shell that repeats rather than develops | "You're filling a template. Which paragraph actually advances the argument — and which is just restating?" | Soft |
| Conventions noise | Frequent errors that impede clarity | "A few sentences are hard to follow — let's clean up the ones that blur your meaning." | Soft (Domain 4 — see posture note) |

### Voice and posture

Inherit the DBQ posture rules (short turns, rubric vocabulary without naming domains, no "great job," ask-before-asserting, **never write for the student**) with **one deliberate departure**:

- **Conventions count.** ACT scores Language Use and Conventions as a full domain, so — unlike the DBQ — the tutor does **not** wholly ignore grammar/mechanics. But conventions are the **lowest-leverage** of the four domains; the tutor flags errors only when they **impede clarity**, and never at the expense of the higher-leverage Ideas/Analysis and Development moves. *How hard* to push here is an open question for Kevin to tune.

### Calibration set

Worked "good turn / bad turn" examples for representative ACT inputs (fence-sitting thesis, summary-without-stance, missing relationship analysis, generic support, one-sided argument, running-out-of-time pacing). Authored with Brian's pedagogical judgment; treated as the source of truth when prose is ambiguous. Stored as test fixtures under `packages/tutor/calibration/act-writing/`.

## Grading assistant (ACT four-domain GA)

- Scores all **four domains** against the verbatim ACT rubric and produces a **2–12 composite**. Whether it simulates one reader (1–6/domain) or two (2–12/domain, then averaged) is an open question.
- **Errors-don't-subtract does NOT apply** here (the DBQ rule) — Domain 4 means conventions legitimately move the score. The GA still weights Ideas/Analysis and Development most heavily, mirroring how the essay actually scores.
- **Feedback is domain-by-domain and retrospective** (post-submit), using ACT rubric language — distinct from the tutor's in-draft coaching. The relationship-analysis move gets called out explicitly.
- Maps 2–12 → gradebook `numericPercentage` / `letterGrade` and to `pointValue` (mapping rule is an open question — linear vs. banded vs. teacher-configured).
- **Calibrated** against ACT's officially published sample essays and their scoring commentaries before any pilot, the same calibration-anchoring approach as the DBQ GA.

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

Best-guess only; engineering will refine (same caveat as the DBQ specs).

- `packages/prisma/schema.prisma` — `AssignmentType.kind` value `'act_writing'`; `Assignment.actWritingPrompt` JSON (option A) or new `ActWritingPrompt` table (option B); reuse `TimedSession`, `Assignment.submitForGrade`/`pointValue`.
- `packages/prisma/migrations/<timestamp>_act_writing_assignment_type/migration.sql` — additive.
- `services/web-app/app/routes/documents/$documentId.tsx` (or the Document route) — branch on `AssignmentType.kind === 'act_writing'` to render the ACT screen.
- `services/web-app/app/components/document/act-writing/` (new) — `prompt-banner.tsx`, `perspectives-panel.tsx`, `essay-editor.tsx` (wraps the shared editor), `timed-mode-banner.tsx`, `tutor-stripe.tsx` (surface; logic in `packages/tutor`).
- `packages/tutor/act-writing/` — `phase-machine.ts`, `detectors/`, `phases/`, `voice.ts`.
- `packages/tutor/rubric/act-writing.json` — the four-domain rubric, verbatim and structured.
- `packages/tutor/calibration/act-writing/` — calibration fixtures.
- Grading-assistant package (wherever the DBQ/thesis GA lives) — `act-writing/` scorer: four-domain scoring + 2–12 composite + percentage/letter mapping.
- The three standardized assignment-creation routes (dashboard / My Classes / assignment-type page) — ACT prompt authoring (issue + three perspectives) and timed/duration controls.
- `packages/db/...` — `TutorSession` / `DetectorFire` rows.
- E2E tests under `services/web-app/tests/e2e/`.

## Open questions

- [ ] **Timed mode in v1 pilot, or untimed-first?** Timed practice is arguably the whole point of ACT prep, but untimed-first de-risks the build. Lean: ship untimed core + timed together since `TimedSession` already exists and ACT only needs a single-phase clock. (Brian / Bryant)
- [ ] **Submit-for-grade default** for ACT practice — ON (standardization default) or OFF for low-stakes timed reps? (Brian / Kevin)
- [ ] **2–12 → gradebook mapping** — linear (e.g. 12 → 100%), banded, or teacher-configured? Affects grade display and future LMS passback. (Brian / Bryant)
- [ ] **GA reader simulation** — one reader (1–6/domain) or two (2–12/domain averaged)? Two-reader better matches real ACT reporting but adds cost/variance. (Kevin / Bryant)
- [ ] **v1 prompt sourcing** — teacher-authored only, an official-style starter library, or both? Drives data-model option A vs. B. (Brian / Kevin)
- [ ] **Canonical rubric** — confirm the current official ACT Writing rubric version and source; store verbatim like the DBQ rubric. ACT has been revising the test, so this must be verified before pilot. (Brian)
- [ ] **Teacher Lounge materials** for ACT Writing in v1? (Brian)
- [ ] **Conventions posture** — how hard should the tutor push on Language Use & Conventions vs. the higher-leverage domains, given errors-don't-subtract does not apply here? (Kevin)
- [ ] **Pilot teacher/org** for ACT Writing — DBQ uses UA → Washington → Birmingham; ACT's pilot is unset. Some schools treat ACT Writing as institutional data — a willing one is the ideal first pilot. (Brian / Bryant)

## Edge cases

- Student writes only their own view and never engages a single given perspective → GA scores low on Ideas and Analysis; tutor's "no relationship analysis" detector should have fired during drafting.
- Student only summarizes the three perspectives with no stance → low Ideas and Analysis; "summary without a stance" detector.
- Timed run: tab closed at minute 5, reopened at minute 20 → resume with ~20 minutes left from server `startedAt`; never restart.
- Timed run: reopened after expiry → already auto-submitted; show submitted state, not the editor.
- Student finishes and submits early → allowed; clock stops.
- Blank or near-empty submission → GA handles gracefully (floor score), no crash.
- Very long perspective text authored by a teacher → perspectives panel scrolls within its card; doesn't push the editor off-screen.
- Teacher authors fewer than three perspectives → validation blocks publish (exactly three required for the ACT format).
- Student opens the same ACT assignment in two tabs → cross-reference the multi-tab editing warning; tutor/timed state must not split-brain.
- Paste a large block into the editor → existing paste-alert policy applies.
- Existing non-ACT assignments and submissions → unaffected by the new `kind` value and prompt column.

## Test plan

- **Unit:** detector firing on labeled ACT-essay snippets (target a low false-positive rate on blocking detectors); 2–12 composite math from four domain scores; 2–12 → percentage/letter mapping.
- **Calibration:** GA scores vs. ACT's published sample essays and scoring commentaries; tutor turns vs. the calibration anchors. Run in CI.
- **Integration:** timed single-phase session (start, countdown, auto-submit at 40 min, resume across tab close); untimed session (no clock, manual submit).
- **Contract:** the GA prompt includes all four rubric domains; assignment type resolves the ACT tutor + ACT GA.
- **E2E:** teacher authors an ACT Writing assignment (issue + three perspectives, timed) → student writes end-to-end → GA returns a four-domain 2–12 score with domain feedback.
- **Regression:** thesis-essay and Daily Pages tutor/GA behavior unchanged; existing assignment creation unaffected.
- **Pedagogy review:** Brian + an ACT-experienced teacher read representative tutor sessions and GA scores before pilot.

## Rollout

Feature flag: `act_writing_assignment_type` (mirrors `dbq_assignment_type`). Default OFF.

1. Land the additive schema (kind value, prompt column, timed reuse) — no behavior change.
2. Land the tutor, GA, and student screen behind the flag; smoke-test in staging.
3. Calibrate the GA against official sample essays; pedagogy review.
4. Pilot with one willing ACT-using teacher/org; default ON after calibration and timed-mode regressions verify.
5. SAT Writing follows as a sibling type, reusing this scaffolding.

**Staged within v1:** if calibration risk surfaces, ship the tutor + screen first with the GA in "feedback-only, no recorded grade" mode (submit-for-grade off), then enable scored mode once GA calibration clears.

## Engineering handoff checklist

- [x] Domain context covered
- [x] File paths in `yawp-2.0` listed
- [x] Data model implications spelled out, including backward-compat plan
- [x] UX sketch in prose
- [x] Edge cases enumerated
- [x] Test plan written
- [x] Rollout plan decided
- [ ] Canonical ACT rubric version confirmed and stored verbatim
- [ ] Timed-in-v1 vs. untimed-first decided
- [ ] 2–12 → gradebook mapping decided
- [ ] Calibration set authored (tutor) and GA calibrated against official samples