pal-e-docs

Review: Email: Welcome to first practice — all teams

review-763-2026-04-03 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, season starts Apr 7
  • [x] Repo — forgejo_admin/basketball-api
  • [x] User Story — clear "who wants what and why"
  • [x] Context — sufficient background for fresh-context agent
  • [x] File Targets — present (but has an error, see below)
  • [x] Acceptance Criteria — 5 testable conditions
  • [x] Test Expectations — present with pytest run command
  • [x] Constraints — references existing patterns and dependencies
  • [x] Checklist — present
  • [x] Related — links to project and parent issue

Traceability

  • [x] story:WS-S7 label — "As an admin, I want to send branded email announcements so that parent comms are professional and consistent"
  • [x] story note verified — found in project-westside-basketball user-stories section (Admin stories list)
  • [x] arch:basketball-api label — basketball-api service component
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-basketball-api for the basketball-api service
  • [x] Forgejo issue — forgejo_admin/basketball-api#312, open

File Targets

  • [x] src/basketball_api/services/email.py — verified: exists, contains 9 existing send_*_email functions including send_jersey_reminder_email reference pattern at line 1140
  • [ ] src/basketball_api/templates/ — ISSUE: this directory does not exist. Email templates are MJML-compiled HTML served from /data/email-templates inside the container (configured via config.py:38 email_templates_dir). MJML source is compiled during Docker build (board items 750, 753 validated). The issue should reference adding an MJML template to the email build pipeline, loaded at runtime via load_email_template("welcome-practice", {...}).
  • [x] src/basketball_api/routes/admin.py — verified: exists, has existing POST /email/jersey-reminder endpoint at line 847 as reference pattern

Repo Placement

OK — issue filed on basketball-api, all code targets are in basketball-api. Note: the MJML template source may live in the Docker build context or a sibling directory, but load_email_template() handles runtime loading from /data/email-templates. Single-repo scope is correct.

Dependencies

  • [x] PracticeSchedule model — satisfied: exists in models.py (line 505) with team_id, division, day_of_week, start_time, end_time, location columns
  • [x] Email infrastructure (gmail-sdk, load_email_template, EmailLog) — satisfied: all in place per validated items 750-753
  • [x] Practice schedule data seeding (issue #279) — referenced as related, assumed satisfied
  • [ ] Board item #733 (in_progress) — 9 failing jersey/checkout tests. CI blocker for deployment, not for development. Pending.
  • [x] Board item #764 (backlog) — sibling email "Local teams — no Monday." Same story/arch. Independent but could share template pattern.

Acceptance Criteria

5 AC, all testable. "Email includes parent-player meeting details" and "personalized per parent with team schedule from DB" are verifiable via test_email param. "Excludes TEST players" is verifiable via query assertion. "Logs to email_log table" is verifiable via DB check. "Supports filter by team_id/division and test_email" is verifiable via endpoint params. No ambiguous criteria.

Blast Radius

Low. Adds one new function to email.py and one new endpoint to admin.py. Follows established patterns (jersey-reminder). PracticeSchedule query is read-only. No schema changes (models.py explicitly excluded). EmailLog insert is append-only. Rollback is straightforward — revert the PR.

Decomposition Assessment

3 file targets (email.py, template, admin.py), 1 repo, 5 AC. All changes are tightly coupled (endpoint calls service function which uses template). Estimated agent time: 3-4 minutes. No independent subtasks to parallelize. No decomposition needed.

Recommendation

  • [BODY] Fix file target: replace src/basketball_api/templates/ with correct guidance. The MJML template should be added to the email build pipeline (Dockerfile copies compiled HTML to /data/email-templates/). At runtime, load_email_template("welcome-practice", {...}) loads from that directory. Point the agent to existing templates in the Docker build context for reference.
  • [SCOPE] Create architecture note arch-basketball-api for the basketball-api service component. This is a cross-cutting gap affecting all basketball-api tickets, not specific to this one.