pal-e-docs

Review: Jersey reminder email shows wrong jersey images — needs division-aware templates

review-893-2026-04-04 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue-bug:
  • [x] Type — Bug
  • [x] Lineage — discovered during jersey reminder blast 2026-04-08
  • [x] Repo — identified (westside-emails + basketball-api)
  • [x] What Broke — clear description: 32 Kings families received Queens jersey images
  • [x] Repro Steps — reproducible: send jersey reminder to any Kings parent
  • [x] Expected Behavior — Kings parents see Kings jerseys, Queens parents see Queens jerseys
  • [x] Environment — template path, send function line, image names all specified
  • [x] Acceptance Criteria — 6 criteria listed
  • [x] Related — project, stories, key files all listed

Traceability

  • [x] story:WS-S22 — "As a parent, I want to receive clear email communications with action links so that I never miss a deadline" — verified in project-westside-basketball user-stories section
  • [ ] arch:westside-app — INCORRECT. The fix targets westside-emails (MJML template) and basketball-api (send logic). Neither is westside-app. [LABEL] Change to arch:email
  • [ ] arch note MISSING — no arch-westside-app note exists in pal-e-docs, and the label itself is wrong for this ticket. [SCOPE] If arch:email is used, verify arch-email note exists or create it.
  • [x] Forgejo issue — forgejo_admin/westside-emails#10, open

File Targets

  • [x] westside-emails/src/jersey-reminder.mjml — verified: exists in Forgejo repo. Compiled HTML confirmed with hardcoded Queens images: IMG_4164.jpeg (line 244) and IMG_4165.jpeg (line 330). Both point to minio-api.tail5b443a.ts.net/assets/westside/jerseys/.
  • [x] basketball_api/services/email.py:1140 — verified: send_jersey_reminder_email exists at line 1140. Currently passes only name and jersey_url placeholders — no division awareness. Function receives players: list[Player] which has access to player.division (confirmed via other email functions in same file).
  • [ ] /tmp/jersey-kings-1.jpeg and /tmp/jersey-kings-2.jpeg — NOT VERIFIED. These are claimed to be downloaded from GroupMe. Cannot confirm they exist at deploy time. [BODY] MinIO upload step should reference a persistent source, not /tmp.

Repo Placement

MISMATCH. Issue filed on forgejo_admin/westside-emails but fix spans TWO repos:
  • westside-emails — MJML template changes (add placeholders)
  • basketball-api — send function changes (pass division-specific URLs)
The board item labels arch:westside-app which is NEITHER affected repo. Two PRs will be needed (one per repo). [LABEL] Fix arch label. [BODY] Document that two PRs are needed.

Dependencies

  • [x] MinIO image upload must happen BEFORE template/code changes can be tested — not yet satisfied
  • [x] Template compilation (MJML to HTML) must happen after template edit, before basketball-api can consume it — pipeline dependency
  • [ ] Kings jersey source images — claimed in /tmp from GroupMe download, not verified as persistent
Board item #876 (backlog, type:bug, arch:basketball-api, story:WS-S18) may be related — also jersey/email scoped. Board item #767 (backlog, "MJML sponsor-outreach template", arch:email) uses same email template pattern.

Acceptance Criteria

  • [x] AC1: "Kings jersey images uploaded to MinIO" — verifiable via MinIO API curl
  • [x] AC2: "Template uses division-specific image placeholders" — verifiable via grep on template
  • [x] AC3: "send_jersey_reminder_email passes correct images based on player division" — verifiable via code inspection
  • [x] AC4: "Test email to Kings parent shows Kings jerseys" — verifiable but requires manual email check
  • [x] AC5: "Test email to Queens parent shows Queens jerseys" — verifiable but requires manual email check
  • [ ] AC6: "Corrected emails resent to 32 Kings families" — this is an OPERATIONAL ACTION, not a code fix. An agent cannot autonomously blast 32 emails (see email_blast_nuclear_gate convention). Must be a separate ticket with blast gate approval.

Blast Radius

Low blast radius for the template fix itself. The load_email_template function is a generic placeholder replacer — adding new placeholders will not break existing ones. However:
  • Other email templates (registration-confirmation) may have similar hardcoded-image issues if divisions matter there.
  • The resend operation (AC6) has HIGH blast radius — 32 real emails to real parents. This MUST go through the email blast gate (7-step approval).

Decomposition Assessment

NEEDS DECOMPOSITION. 6 AC across 2 repos + MinIO upload + operational email resend. Estimated agent time well over 5 minutes. Three discrete change areas exceed the three-thing limit.
Recommended split:
  • Ticket A: Upload Kings images to MinIO, rename Queens images (infra/ops task, 1 repo: MinIO CLI)
  • Ticket B: Make jersey-reminder template division-aware + update send function (code change, 2 repos: westside-emails + basketball-api)
  • Ticket C: Resend corrected emails to 32 Kings families (operational, requires blast gate approval — separate from code work)
Route to skill-decompose-ticket for automated sub-ticket creation.

Recommendation

  • [LABEL] Change arch:westside-app to arch:email — the fix is in westside-emails and basketball-api, not westside-app
  • [SCOPE] Verify or create architecture note for the email system (arch-email or equivalent)
  • [BODY] Clarify that Option B is the chosen approach — issue presents two options without a decision
  • [BODY] Remove AC6 (resend) from this ticket — operational blast must go through email blast gate as a separate ticket
  • [BODY] Replace /tmp image paths with persistent source (GroupMe download link or MinIO staging path)
  • [BODY] Document that two PRs are needed (one per repo)
  • [DECOMPOSE] 6 AC across 2 repos + MinIO + operational resend — route to skill-decompose-ticket. Recommended 3-ticket split.