Review: incomplete_profiles query for email blast

Verdict: READY

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, references email agent capability buildout
• [x] Repo — forgejo_admin/basketball-api
• [x] User Story — As an admin, I want to send profile completion reminders
• [x] Context — Database audit numbers, profile URL pattern, relationship to blast endpoint
• [x] File Targets — email_queries.py to modify, admin.py and email.py excluded with reasons
• [x] Acceptance Criteria — 5 criteria, all testable
• [x] Test Expectations — 4 unit tests, run command specified
• [x] Constraints — Pattern reference, result dict requirements, URL construction
• [x] Checklist — Standard 3-item checklist
• [x] Related — arch-email, project-westside-agency, Issue #295

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 — WS-S7 found in project-westside-basketball user-stories section (Admin stories)
• [x] arch:email label — email architecture component
• [ ] arch note MISSING — [SCOPE] Create architecture note arch-email for the email component. No matching note found in pal-e-docs.
• [x] Forgejo issue — forgejo_admin/basketball-api#308, state: open

File Targets

• [x] src/basketball_api/services/email_queries.py — verified on origin/main (commit fb24245). File exists with QUERY_REGISTRY dict and query_unsigned_contracts as the pattern to follow. Issue correctly says "modify" (add new function + register).
• [x] src/basketball_api/routes/admin.py — correctly excluded (blast endpoint is generic, dispatches via QUERY_REGISTRY)
• [x] src/basketball_api/services/email.py — correctly excluded (send_profile_reminder_email is a separate older path)
• [x] Player model fields verified: photo_url (line 205), height (line 202), position (line 203), date_of_birth (line 206) — all nullable, match issue description
• [x] registration_token field verified on Parent model (line 183) — profile_url pattern confirmed in email.py line 92

Repo Placement

Dependencies

• [x] Issue #295 (blast endpoint + QUERY_REGISTRY) — done, validated:pass (board item #752). Provides the /email/blast endpoint and QUERY_REGISTRY infrastructure this query plugs into.
• [x] Issue #294 (send_templated_email) — done, validated:pass (board item #751). Provides the email sending mechanism.
• [x] Issue #293 (MJML system) — done, validated:pass (board item #750). Provides templates.
• No blocking dependencies. All upstream work is complete and validated.

Acceptance Criteria

• Query returns per-player rows for missing fields — testable via unit test with fixture data
• Result dict shape (to, parent_id, parent_name, player_name, team_name, missing_fields, profile_url) — testable via assertion on dict keys
• test_email filtering — testable, follows existing pattern in query_unsigned_contracts
• Complete players excluded — testable with fixture player that has all fields
• Jersey number/size NOT checked — testable by ensuring players missing only those fields are excluded

Blast Radius

Decomposition Assessment

• File targets: 1 file to modify (email_queries.py), 1 test file to extend (test_email_blast.py) — under 3-file limit
• Acceptance criteria: 5 — at the limit but all tightly related (single query function)
• Single repo: forgejo_admin/basketball-api
• Estimated agent time: 3-4 minutes — within 5-minute rule
• No independent subtasks that would benefit from parallelization

Recommendation

• [SCOPE] Create architecture note arch-email for the email component. Multiple board items (12+) reference arch:email but no backing note exists in pal-e-docs. Non-blocking for this ticket — track as separate backlog item.