pal-e-docs

Review: Seed practice_schedules table with Spring/Summer 2026 schedule

review-739-2026-04-03 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered while verifying schedule data
  • [x] Repo -- forgejo_admin/basketball-api
  • [x] User Story -- clear as-a/I-want/so-that
  • [x] Context -- clear motivation, season start date, table state
  • [x] File Targets -- listed (data-only, explicit "do not touch" list)
  • [x] Acceptance Criteria -- 5 criteria with full 17-row data table
  • [x] Test Expectations -- SQL count verification + API curl
  • [x] Constraints -- tenant_id, data-only, source of truth noted
  • [x] Checklist -- present
  • [x] Related -- project + source note referenced

Traceability

  • [x] story:WS-S13 label -- "As an admin, I want to view and manage the program schedule (practices, tournaments, games) so that I have a single source of truth for all planned activities"
  • [x] story note verified -- WS-S13 found in project-westside-basketball user-stories section under Admin (Marcus)
  • [x] arch:schedule label -- present on board item
  • [ ] arch note MISSING -- [SCOPE] search for "arch-schedule" returned 0 results in pal-e-docs. Create architecture note arch-schedule for the schedule component.
  • [x] Forgejo issue -- forgejo_admin/basketball-api#279, open

File Targets

  • [x] src/basketball_api/models.py -- verified exists (PracticeSchedule model at line 505). Correctly marked "do not touch."
  • [x] src/basketball_api/routes/schedule.py -- verified exists with CRUD endpoints. Correctly marked "do not touch."
  • [x] alembic/versions/029_add_schedule_tables.py -- verified exists. Correctly marked "do not touch."
  • [ ] scripts/seed_practice_schedules.sql -- ISSUE: ticket proposes creating a new SQL file, but scripts/seed_schedule.py already exists as a Python seed script with placeholder data (generic labels, no team_id mapping). [BODY] Clarify whether to update scripts/seed_schedule.py with real Spring/Summer 2026 data or create a separate SQL file. Updating the existing Python script is more consistent with repo conventions.

Repo Placement

OK. Issue filed on basketball-api, seed data targets basketball-api. Single-repo scope, no cross-repo concerns.

Dependencies

  • [x] Board item #629 (Schedule data model + migration + seed) -- done, pr:234-merged. Schema is in place.
  • [x] Board item #630 (Schedule API endpoints CRUD) -- done, pr:236-merged. Endpoints deployed.
  • [x] Board item #653 (Public schedule endpoint GET /public/schedule) -- done, pr:241-merged. Public consumers ready.
  • [x] 7 teams exist in teams table -- stated in issue context.
  • No blocking items in in_progress. Safe to execute once scope issues resolved.

Acceptance Criteria

5 acceptance criteria -- testable and specific. The 17-row data table is excellent: agent has exact team_id, day_of_week, times, locations, and notes for every INSERT.
CRITICAL issue with AC #2: "Sunday rows have NULL start_time/end_time until times confirmed." The SQLAlchemy model declares start_time: Mapped[str] and end_time: Mapped[str] (non-nullable). Inserting NULL via ORM will raise IntegrityError. Two options: (1) use sentinel value like empty string or "TBD" instead of NULL (no schema change), or (2) change model to Mapped[str | None] with nullable=True (requires migration, contradicts "data-only" constraint). [BODY] Resolve this conflict before dispatch.
Minor: the kubectl exec test command references postgres-... placeholder. Agent can discover pod name -- not blocking.

Blast Radius

  • routes/public.py queries practice_schedules with is_active=True filter -- new rows appear on public schedule page immediately. Intended behavior.
  • westside-app admin schedule view (board item #639, done) consumes GET /admin/schedule/practices -- will show new data immediately. No concern.
  • No other repos consume the practice_schedules table.
  • Rollback: DELETE FROM practice_schedules. Straightforward.

Decomposition Assessment

1 file target (seed script), 5 AC, single repo, estimated under 5 minutes. Fits the three-thing limit and five-minute rule. No decomposition needed.

Recommendation

  • [BODY] Resolve NULL start_time/end_time conflict: model declares Mapped[str] (non-nullable) but AC #2 requires NULL for Sunday rows. Either update AC to use sentinel value (e.g. "TBD"), or acknowledge that a model change + migration is in scope and update Constraints section accordingly.
  • [BODY] Clarify seed mechanism: existing scripts/seed_schedule.py has placeholder data. Recommend updating it with real Spring/Summer 2026 data instead of creating new scripts/seed_practice_schedules.sql -- Python seed scripts are the repo convention.
  • [SCOPE] Create architecture note arch-schedule for the schedule component in pal-e-docs.