pal-e-docs

Review: email_blast tool for NEMO

review-759-2026-04-03 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — standalone, part of westside-email-agent capability
  • [x] Repo — forgejo_admin/westside-ai-assistant
  • [x] User Story — clear admin-to-NEMO email flow
  • [x] Context — thorough, references existing patterns and auth
  • [x] File Targets — specific files with modify/do-not-touch
  • [x] Acceptance Criteria — 6 testable items
  • [x] Test Expectations — 3 unit tests with run command
  • [x] Constraints — patterns, auth, prompt guidance
  • [x] Checklist — standard 3-item
  • [x] Related — arch-email, sop-email-send, project-westside-agency, basketball-api #295

Traceability

  • [ ] story:WA-S1 label — NO matching story on project-westside-ai-assistant user-stories section. Project page lists: read-ops, write-ops, safety. "WA-S1" does not exist. [SCOPE] Create user story entry "WA-S1" on project-westside-ai-assistant user-stories section, OR relabel to an existing story (e.g., story:write-ops if email blast is considered a write operation).
  • [x] arch:email label — arch-email note exists (id 1102, project westside-basketball, tagged architecture+active). Substantive content covers layouts, components, blast flow.
  • [x] Forgejo issue — forgejo_admin/westside-ai-assistant#31, open

File Targets

  • [x] app/ai.py — verified: TOOLS list at line 49, SYSTEM_PROMPT at line 24, existing write tools (update_player, assign_player_to_team) with metadata operation=write pattern confirmed. Tool execution handler at line 246+.
  • [x] app/basketball.py — verified: BasketballClient class at line 25, only has get() method (line 134). No post() exists yet — matches ticket claim.
  • [x] app/confirmation.py — exists, correctly marked NOT to touch.
  • [x] app/groupme.py — exists, correctly marked NOT to touch.
  • [x] app/config.py — exists, correctly marked NOT to touch.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, all file targets are in that repo. No cross-repo work needed — basketball-api blast endpoint already exists and is deployed.

Dependencies

  • [x] basketball-api #295 (blast endpoint) — satisfied. Issue closed, merged (commit fb24245), deployed on origin/main.
  • [x] Board item #599 (GroupMe bot go-live) — in_progress. Not a hard blocker (email_blast tool can be built and tested independently), but full end-to-end flow requires bot to be live.
No unresolved dependencies that would block execution.

Acceptance Criteria

6 ACs, all agent-verifiable:
  • AC1: email_blast tool in TOOLS with correct schema — grep/read verification
  • AC2: Tool tagged as write operation — grep verification of metadata
  • AC3: BasketballClient.post() method exists — grep verification
  • AC4: SYSTEM_PROMPT includes email capabilities — read verification
  • AC5: End-to-end flow (user says X, NEMO proposes, user confirms, blast executes) — testable via unit test mock
  • AC6: test_email parameter works — unit test
All criteria are concrete and testable. No ambiguity.

Blast Radius

Low. Changes are additive (new tool + new method). Existing tools and confirmation flow are untouched. The basketball-api blast endpoint already handles auth and validation — this ticket only adds the client-side caller. No sibling services consume NEMO's tool definitions. Rollback is straightforward (revert the two file changes).

Decomposition Assessment

2 files in 1 repo. 6 acceptance criteria. Estimated agent time ~3-4 minutes. All changes are tightly coupled (tool definition + client method + prompt update). No independent subtasks worth parallelizing. No decomposition needed.

Recommendation

  • [SCOPE] Story "WA-S1" does not exist on project-westside-ai-assistant user-stories section. Either create a new user story entry for email/agent-driven-communications capability, or relabel the board item to an existing story (e.g., story:write-ops). This must be resolved before the ticket can move to next_up.