pal-e-docs

Review: Team detail page contract (Mismatch 9)

review-744-2026-04-03 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — References spike #278
  • [x] Repo — forgejo_admin/basketball-api + forgejo_admin/westside-landing
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria (6 items)
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

Traceability

  • [x] story:WS-S12 label — verified in project-westside-basketball user-stories
  • [x] arch:basketball-api label — present on board item
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-basketball-api
  • [x] Forgejo issue — forgejo_admin/basketball-api#284, open

File Targets

  • [x] src/basketball_api/routes/teams.py — verified: TeamDetail at line 83 has coach: CoachBrief | None (singular). CoachBrief at line 62 has id, name, email only (no role, phone). PlayerBrief at line 53 has id, name, division, position (no height, jersey_number). Ticket accurately describes what needs changing.
  • [x] src/routes/(app)/teams/[id]/+page.svelte (westside-app) — verified: Frontend ALREADY uses team.coaches (plural array), coach.role, and coach.phone. This means the frontend is ahead of the API — the API change will make the frontend work correctly rather than needing a frontend update.
  • [ ] File target path mismatch — [BODY] Issue says src/routes/teams/[id]/+page.svelte but actual path is src/routes/(app)/teams/[id]/+page.svelte (SvelteKit route group)

Repo Placement

ISSUE: This is filed as a cross-repo ticket (basketball-api + westside-landing) on the basketball-api repo. However, the frontend already consumes the plural coaches array — the frontend work may not be needed. The API-side work alone would fix the mismatch. If frontend changes ARE needed, this should be two separate Forgejo issues (one per repo) per convention. The issue is filed on basketball-api but westside-landing has no corresponding issue.

Dependencies

  • [x] Breaking change: coach (singular) to coaches (plural) — ticket correctly notes coordinated deploy needed.
  • [ ] Frontend already uses coaches array — the "breaking change" concern may be moot since the frontend is already coded for the new contract.

Acceptance Criteria

6 AC items spanning 2 repos. AC #5 ("Frontend teams/[id]/+page.svelte updated to iterate coaches array") appears unnecessary — frontend already does this. The AC should be verified and potentially removed or replaced with "verify frontend renders correctly with updated API response."

Blast Radius

The coach singular-to-plural change is a breaking API change. However, since the frontend already expects the plural form, coordinated deploy risk is LOW. Any other API consumers expecting coach (singular) would break.

Decomposition Assessment

Cross-repo ticket with 6 AC. However, the frontend work appears unnecessary (already done). If scoped to API-only: 1 file, 3 model changes, <5 minutes. If cross-repo work is truly needed: NEEDS DECOMPOSITION into 2 tickets (one per repo). Current assessment: refine scope first, then re-evaluate.

Recommendation

  • [BODY] Fix frontend file path: src/routes/teams/[id]/+page.svelte should be src/routes/(app)/teams/[id]/+page.svelte
  • [BODY] Verify whether frontend AC #5 is needed — frontend already uses team.coaches array, coach.role, and coach.phone. If no frontend changes needed, remove frontend scope and re-scope as API-only ticket.
  • [BODY] If frontend changes ARE needed, split into two Forgejo issues (one per repo) per one-ticket-one-repo convention.
  • [SCOPE] Create architecture note arch-basketball-api