pal-e-docs

Review: Spike: audit API response contract mismatches with westside-landing

review-738-2026-04-03 Doc

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type — Spike
  • [x] Lineage — References #276 and #203 (parent phone bug prompted systemic investigation)
  • [x] Repo — Multiple (basketball-api + westside-landing), correctly identified
  • [x] Question — Well-framed: how many mismatches, fix at API/frontend/both?
  • [x] What to Explore — Detailed 5-step investigation approach + 5 specific models named
  • [x] Success Criteria — 4 criteria, all verifiable
  • [x] Time-box — 1 session (appropriate for spike)
  • [x] Related — project-westside-basketball + 2 related issues
All 8 spike template sections present and complete.

Traceability

  • [x] story:WS-S12 label — "As an admin, I want to manage user accounts (reset passwords, view profiles) so that I can support parents directly"
  • [x] story note verified — found in project-westside-basketball user-stories section (Admin stories list)
  • [x] arch:basketball-api label — basketball-api component
  • [ ] arch note MISSING — [SCOPE] No arch-basketball-api note found in pal-e-docs via search_notes. Create architecture note arch-basketball-api for component basketball-api.
  • [x] Forgejo issue — forgejo_admin/basketball-api#278, open

File Targets

Spike type — no file targets required by template. However, the issue names specific models to investigate. All verified as existing in the codebase:
  • [x] AdminPlayerItem in routes/admin.py:289 — confirmed. Missing parent_phone field; frontend (admin/players/+page.svelte:297) expects player.parent_phone.
  • [x] IncompletePlayerItem in routes/admin.py:403 — confirmed. Has parent_email, parent_name but no parent_phone.
  • [x] SubscriptionListItem in routes/subscriptions.py:57 — confirmed. Has parent_name, parent_email but no parent_phone.
  • [x] PlayerProfileResponse in routes/players.py:40 — confirmed. Uses nested parent: ParentInfo (id, name, email, phone) while frontend expects flat player.parent_phone, player.parent_email.
Targets are specific enough for the spike agent to begin investigation immediately.

Repo Placement

OK. Issue correctly filed on basketball-api (primary investigation target). Issue body explicitly notes cross-repo scope (basketball-api + westside-landing). Spike output = follow-up tickets, which would be filed on each respective repo. No mismatch.

Dependencies

  • [x] #276 (parent phone API fix) — satisfied (merged)
  • [x] #203 (parent phone frontend fix) — satisfied (merged)
  • [x] No in_progress items blocking this spike
No unresolved dependencies.

Acceptance Criteria

4 success criteria from the issue, all agent-verifiable:
  • [x] "Complete inventory of all response models with parent/team/coach data" — verifiable via grep across routes directory
  • [x] "Each mismatch documented with field name, API shape, frontend expectation, visible impact" — verifiable by reviewing spike output structure
  • [x] "Recommendation: API-first fix, frontend-first fix, or both" — verifiable by presence of conclusion
  • [x] "Follow-up bug/feature tickets created for each actionable mismatch" — verifiable via Forgejo issue search
All criteria are testable and specific. No ambiguous language.

Blast Radius

Spike is read-only investigation — zero blast radius from execution. The investigation correctly scopes to all response models (not just the 4 known ones). Coach route models (coaches_api.py, coach.py), roster models (roster.py), and team models (teams.py) should also be checked — the "What to Explore" step 1 ("list all Pydantic response models") would catch them organically. No rollback concerns.

Decomposition Assessment

Three-thing limit and five-minute rule assessment:
  • Single-agent investigation spike — 0 code changes, 2 repos to read
  • 4 success criteria, all achievable in one pass
  • Estimated agent time: well within 5 minutes (grep + read operations only)
  • No independent subtasks requiring parallelization
No decomposition needed.

Recommendation

  • [SCOPE] Create architecture note arch-basketball-api for component basketball-api in pal-e-docs. This is a documentation gap, not a scope blocker for spike execution.
All other aspects are solid. Ticket is ready for agent dispatch.