Batch grading

# Batch grading

Teachers grade an entire batch of submissions without clicking into each paper, waiting for GA to generate, and clicking back. The batch-release flow already exists and works well; batch grading should be the upstream sibling.

## Problem

Today, the GA workflow forces a teacher to:

1. Click into a single submission.
2. Wait for GA to generate.
3. Cannot leave the window — leaving cancels grading.
4. Click back, click the next paper, wait again.

For a class of 30 students, this is a serial bottleneck. Reported repeatedly (Feb 27, Mar 3) as the single biggest workflow drag on grading sessions. The "can't leave the window or it cancels" constraint makes the wait actively painful — the teacher can't multitask.

## Goals

- Teacher selects a batch of submissions (check-all or individual checkboxes) and triggers GA on all of them via the existing "Grade with AI" button.
- Generation runs server-side in the background; teacher can leave the window without cancelling.
- Tab badges on Submitted/Graded/Released show counts — as papers finish grading, the number drains from Submitted and fills in Graded. No other notification needed.
- From the Graded tab, teacher walks through papers and releases as they go — no round-trip back to the list.

## Non-goals

- Auto-release without teacher review. Human-in-the-loop stays.
- Batch grading across courses. Scope is per-course-per-assignment, like batch release today.
- Push notifications or email when a batch completes — tab badge is sufficient.

## UX sketch

Entry point is the assignment submission list (visible in course view PR #101). Already has checkboxes per row and a check-all header, plus a "Grade with AI" button.

```
Submitted (11)  Graded (0)  Released (0)  In Progress

[Grade with AI]

☑  Student          Submission           Submitted       Status
☑  Jane Smith       Personal Statement   2 min ago       Ungraded
☑  John Doe         Personal Statement   6 min ago       Ungraded
   ...
```

Teacher checks all → clicks "Grade with AI" → submissions enter a server-side queue.

While grading runs, the Submitted count drains and Graded count fills as each paper completes:

```
Submitted (4)  Graded (7)  Released (0)  In Progress
```

If GA fails on a paper, it stays in Submitted as Ungraded — no error flag, no special status. Teacher will notice it didn't move and can retry or grade manually.

Once all done, teacher clicks into Graded tab, reviews each paper, and releases from there without leaving the view.

## Domain notes

Mirrors existing batch-release functionality on the same domain entities (Submission). Batch grading happens before release; batch release is already shipped. Together they form: select batch → grade in background → review and release as a batch.

## Concurrency and throttling

Batch grading must throttle requests to the LLM — do not fire all submissions simultaneously. The upstream error bug ([bugs/batch-feedback-upstream-error.md](../bugs/batch-feedback-upstream-error.md)) crashed the site with only 12 concurrent requests; a class of 30 would exceed that easily.

Engineering decision for Bryant: implement a queue that sends N submissions at a time (suggested: 5), with the remainder waiting. This is a required design constraint, not optional. Whether to also fix the root cause of the upstream error bug is a separate call — flag it when you pick this up.

May 7 sync: keep this out of ready-for-engineering until the spec lands on a concrete background-job model, retry/failure behavior, likely `yawp-2.0` file paths, and rollout gate. The upstream-error bug should inform queue depth, but it should not stop the rest of the product design from being made explicit.

## Open questions — needs Bryant before ready-for-engineering

The following are blockers for handoff. Bryant needs to weigh in before this spec can move forward.

- [ ] **Concurrency limit** — what's the right queue depth? 5 at a time is suggested, but the right number depends on what the upstream error investigation (`bugs/batch-feedback-upstream-error.md`) actually reveals about the provider's per-key limit.
- [ ] **Data model** — how should a background grading job be represented? New jobs/queue table, a status field on Submission, or something else? Needs a migration plan and backward-compat story.
- [ ] **File paths** — which files in `yawp-2.0` are most likely to change?
- [ ] **Edge cases** — what happens to a queued submission if it's archived mid-batch? If GA errors, does the submission stay Ungraded silently (current sketch) or should there be a retry mechanism?
- [ ] **Test plan and rollout** — feature flag strategy, which pilot schools get early access, what the validation gate is before broad release.

## Engineering handoff

Not ready yet — data model, file paths, edge cases, test plan, and rollout still needed.