pal-e-docs

Review: Add downstream consumer check to migration workflow

review-468-2026-03-27 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — discovered during incident westside-contracts #25
  • [x] Repo — forgejo_admin/basketball-api
  • [x] User Story — well-formed As a/I want/So that
  • [x] Context — explains shared DB pattern, migration 019 incident, 2-day outage
  • [x] File Targets — 2-3 files to create, plus explicit DO NOT TOUCH section
  • [x] Acceptance Criteria — 3 items, all verifiable
  • [x] Test Expectations — N/A acknowledged (docs-only ticket)
  • [x] Constraints — lightweight convention, match existing style, no over-engineering
  • [x] Checklist — present (missing "Tests pass" but acceptable for docs-only)
  • [x] Related — references project-westside-basketball and incident issue

Traceability

  • [x] story:WS-S5 label — team management story
  • [x] arch:basketball-api label — correct architecture component
  • [x] Forgejo issue — forgejo_admin/basketball-api#193, open

File Targets

  • [x] CONTRIBUTING.md — does not exist yet, to be created. Repo root confirmed at ~/basketball-api/.
  • [x] docs/migrations.md — docs/ directory does not exist yet, to be created.
  • [x] alembic/README.md — does not exist yet, to be created. alembic/ directory confirmed (contains env.py, script.py.mako, versions/).
  • [x] alembic/versions/* — DO NOT TOUCH verified. 27 migration files exist, including 019_player_teams_junction.py (the incident migration).

Repo Placement

Correct. Issue filed on basketball-api, all file targets are within basketball-api. No cross-repo changes needed.

Dependencies

  • Board item #417 "Critical: Migrate basketball-api Postgres to CNPG" (next_up on board-pal-e-platform, story:WS-S5) — related but NOT a blocker. This ticket is documentation/process; #417 is infrastructure migration. Independent.
  • No blocking dependencies. No items in in_progress or next_up on board-westside-basketball.

Acceptance Criteria

All 3 AC are verifiable by an agent:
  • AC1: Shared tables documented — verify created file lists players, teams, parents, player_teams with westside-contracts as consumer.
  • AC2: Migration checklist includes downstream check — verify alembic/README.md contains checklist.
  • AC3: Documentation discoverable from alembic directory — verify alembic/README.md exists.

Blast Radius

Verified downstream consumers of basketball-api Postgres:
  • westside-contracts — confirmed direct SQL via postgres.basketball-api.svc.cluster.local. Queries players, teams, parents, player_teams. Files: src/lib/db.ts, src/routes/contract/[token]/sign/+server.ts, src/routes/contract/[token]/+page.server.ts.
  • No other repos consume basketball-api's database directly.
Note: westside-contracts still has p.team_id remnants in sign/+server.ts and types.ts from the migration 019 incident. Not in scope here but confirms the documentation need.

Decomposition

2-3 new documentation files. 3 acceptance criteria. Estimated agent work: 2-3 minutes. No decomposition needed.

Recommendation

No action needed. Ticket is well-scoped and ready for execution.