pal-e-docs

Review: Email: Welcome to first practice — all teams (re-review)

review-763-2026-04-03-v2 Doc

review ready
Project

Verdict: APPROVED

Re-review of board item #763 after refinement. Previous review: review-763-2026-04-03 (NEEDS_REFINEMENT).

Previous Issues — Resolution

  • [BODY] Wrong template path — FIXED. Issue body now correctly documents the load_email_template() pipeline at email.py:1107, references /data/email-templates/ runtime directory, and gives the agent flexibility to use MJML pipeline or inline HTML.
  • [SCOPE] Missing arch note — Acknowledged as non-blocking backlog item. This is a cross-cutting gap affecting all basketball-api tickets, not specific to this one. Does not block execution.

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 including template pipeline documentation
  • [x] File Targets — corrected, now accurately describes email.py, admin.py, and template options
  • [x] Acceptance Criteria — 5 testable conditions
  • [x] Test Expectations — present with pytest run command
  • [x] Constraints — references existing patterns, load_email_template(), gmail-sdk
  • [x] Checklist — present
  • [x] Related — links to project and parent issue #279

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 (non-blocking backlog item, cross-cutting gap)
  • [x] Forgejo issue — forgejo_admin/basketball-api#312, open

File Targets

  • [x] src/basketball_api/services/email.py — verified: exists, load_email_template() at line 1107, send_jersey_reminder_email at line 1140 as reference pattern
  • [x] src/basketball_api/routes/admin.py — verified: exists, POST /email/jersey-reminder at line 847 as reference pattern
  • [x] Email template — issue now correctly describes MJML pipeline or inline option, no longer references nonexistent src/basketball_api/templates/

Repo Placement

OK — issue filed on basketball-api, all code targets are in basketball-api. Single-repo scope is correct.

Dependencies

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

Acceptance Criteria

5 AC, all testable. Parent-player meeting details, personalized team schedule from DB, filter by team/division, exclude TEST players, log to email_log. No ambiguity. An agent can verify each criterion after implementation.

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. EmailLog insert is append-only.

Decomposition

3 file targets, 1 repo, 5 AC. All tightly coupled. Estimated agent time: 3-4 minutes. No decomposition needed.

Recommendation

No action needed. Ticket is ready for execution.