Yawp Reporter v1

# Yawp Reporter v1

A reporting layer that turns Yawp's writing, feedback, revision, and assignment data into teacher/admin insight: single-student reports, class-level reports, longitudinal progress, district trends, and conversational follow-up.

## Source

Granola meeting: `3fbd5f2d-e409-42bd-b585-fed305edd5cd`, **Summer priorities — assignment types, LMS integration, and reporter**, 2026-05-26 1:31 PM CDT.

The meeting positioned Reporter as a primary differentiation/moat. The call explicitly mentioned single-student/single-essay reports, whole-class analysis on specific assignments, longitudinal tracking, district-wide analytics, conversational follow-up, instructional coaching recommendations, fun data elements like word counts/time spent/pages written, and salvaging prior writing lessons work.

## Problem

Yawp collects unusually rich writing data, but teachers and administrators currently have to infer patterns manually by opening individual submissions, grade views, and student histories.

Teachers need:

- What happened on this assignment?
- Which students need help?
- What should I teach next?
- How is one student changing over time?

Administrators need:

- Are students writing more?
- Are teachers using the platform?
- Are outcomes improving?
- Where should instructional coaching focus?

## Goals

- Give teachers useful reports at the level they naturally ask about: one submission, one student, one class, one assignment, and a time range.
- Surface instructional next steps, not just charts.
- Support conversational follow-up: "Which students struggled with thesis statements?" or "What should I reteach tomorrow?"
- Reuse existing Yawp data before adding new capture burden.
- Make Reporter a reason to keep using Yawp even after grading is complete.

## Non-goals

- Replacing the gradebook.
- Making district accountability claims before data quality is validated.
- Building every analytics screen at once.
- Showing AI confidence as if it were a formal assessment metric.
- Exporting student data broadly before privacy/permission rules are explicit.

## Report types

### 1. Single student, single essay

Answer:

- What is this student's current performance on this submission?
- What did they revise?
- What feedback did they receive?
- What should they work on next?

### 2. Whole class, one assignment

Answer:

- What patterns appeared across the class?
- Which rubric categories were strongest/weakest?
- Which students need a conference?
- Which mini-lesson should happen next?

This is the strongest MVP candidate because it maps directly to a teacher's next-day planning loop.

### 3. Longitudinal student tracking

Answer:

- How has this student changed across weeks/months?
- What are recurring strengths/weaknesses?
- Did revision behavior improve?
- Are Daily Pages signals changing?

### 4. District/admin analytics

Answer:

- How much writing is happening?
- Which schools/classes are active?
- How many assignments, pages, words, submissions, revisions?
- Which groups need coaching/support?

### 5. Conversational follow-up

Teacher asks natural questions and Reporter answers from scoped Yawp data with source links.

Examples:

- "Who needs help with evidence?"
- "What should I reteach before the next DBQ?"
- "Which students improved most since February?"
- "Show me the students who wrote a lot but scored low."

Implementation note: the conversational layer should query generated report facts/snapshots first, not freeform scrape every raw document on every question.

## Fun data elements

Include motivating/legible data, not only formal rubric data:

- Words written.
- Pages written.
- Time spent writing.
- Revision count.
- Submission count.
- Prompt/assignment completion.
- Most active writing days.
- Growth streaks.
- Tutor engagement where appropriate.

## Writing lessons salvage

The meeting referenced prior writing lessons work: roughly 15 lessons with AI-generated variations and an existing voice/instructional design.

Reporter should be able to recommend lessons when a pattern appears:

- Class struggles with evidence -> suggest evidence mini-lesson.
- Student repeatedly misses thesis -> suggest thesis practice.
- DBQ sourcing is weak -> suggest sourcing drill.
- Daily Pages show thin engagement -> suggest idea-development prompt.

First small PR path: recover and catalog the lesson corpus in a teacher-only library before wiring automatic recommendations. See [Writing lessons revival](writing-lessons-revival.md).

## UX sketch

Teacher class report:

```text
Class Report
  Filters: Class | Assignment | Date range | Assignment type

  What happened
    - 27 submissions
    - 18,420 words written
    - 61 revisions

  Patterns
    - Strong: thesis clarity
    - Needs work: evidence integration

  Students to check in with
    - ...

  Suggested next lesson
    - Evidence sandwich mini-lesson

  Ask a follow-up
    [Which students need help with context?]
```

Student report:

```text
Student Writing Report
  Trend: grades, rubric dimensions, word volume, revision behavior
  Strengths
  Recurring areas to work on
  Recent evidence
  Recommended next assignment / lesson
```

Admin report:

```text
District Writing Pulse
  Active teachers/classes
  Assignments created
  Submissions graded
  Words/pages written
  Engagement by school
  Coaching opportunities
```

## Data model implications

Start with derived/reporting views rather than replacing transactional data.

Likely additions:

- `ReportRun`
  - scope, filters, requester, generatedAt, status, result version.
- `ReportInsight`
  - reportRunId, insight type, source references, generated text, confidence/quality metadata.
- `WritingMetricSnapshot`
  - student/class/assignment/time-window rollups for word count, revision count, time spent, submissions, rubric aggregates.
- `InstructionalRecommendation`
  - linked lesson/drill/resource, reason, target scope.

Backward compatibility:

- Existing submission/document/grading records remain canonical.
- Report snapshots are additive and regenerable.
- AI-generated report text should store source pointers so it can be audited/regenerated.

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

- `packages/prisma/schema.prisma` - report run/snapshot/recommendation tables if persisted.
- `services/web-app/app/services/reporter/*` - aggregation and insight generation.
- `services/web-app/app/routes/app.reporter/route.tsx` - Reporter landing/dashboard.
- `services/web-app/app/routes/app.reporter.student.$studentId/route.tsx` - student report.
- `services/web-app/app/routes/app.reporter.class.$classId/route.tsx` - class report.
- `services/web-app/app/routes/api.reporter.*` - follow-up question/report generation endpoints.
- `services/web-app/app/services/released-grades.server.ts` - reuse class/submission aggregation.
- `services/web-app/app/routes/app.my-classes.$classId/*` - entry points from class pages.
- `services/web-app/e2e/tests/reporter.spec.ts` - teacher report flow.

## Open questions

- [ ] Which v1 report ships first: class-assignment report, single-student report, or district engagement dashboard? Default recommendation: class-assignment report first.
- [ ] Should Reporter be teacher-only at first, or should admins get a district pulse in v1?
- [ ] Which data is safe to use for AI follow-up before privacy/legal review?
- [ ] Where do the 15 prior writing lessons live, and what format are they in?
- [ ] Should reports be generated on demand, cached nightly, or both?
- [ ] What exact threshold makes a recommendation "actionable" rather than noisy?
- [ ] Can students see any version of their own report, or teacher/admin only?
- [ ] Should reports cite specific student excerpts, anonymized patterns, or aggregate findings only?
- [ ] Which engagement events are reliable today: time spent, revision attempts, word count, score deltas?

## Edge cases

- Class with too few submissions to produce a meaningful pattern.
- Student with one submission only.
- Daily Pages and formal essays mixed in one time range.
- Teacher edits/overrides GA grades after a report was generated.
- Assignment type has a custom rubric that does not map cleanly to standard dimensions.
- A student's work is archived/deleted under retention rules.
- Admin report includes multiple schools with different feature flags enabled.

## Test plan

- Unit: metric aggregation from seeded submissions/revisions produces expected counts.
- Unit: report filters scope by teacher/class/org permissions.
- Unit: recommendation selection maps weak rubric dimensions to lesson IDs.
- Integration: class report for one assignment includes only that assignment's submissions.
- Integration: student report includes chronological writing history and excludes other students.
- Integration: follow-up question uses scoped report data only.
- E2E: teacher opens class report, filters by assignment, sees patterns and students to check in with.
- E2E: teacher asks a follow-up and sees an answer with linked source submissions.

## Rollout

Feature flag: `feature_yawp_reporter`.

Staged path:

1. Internal report using seeded/demo data.
2. Teacher-only class-assignment report for one pilot class.
3. Single-student longitudinal view.
4. Conversational follow-up.
5. Admin/district pulse.
6. Lesson recommendations once prior lesson corpus is cleaned up.

## 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
- [ ] V1 report type selected
- [ ] Prior writing lessons located/reviewed