pal-e-docs

Review: Fix ruff format on email.py — CI deploy blocker

review-791-2026-04-03 Doc

review ready
Project

Verdict: READY

Retroactive review of a direct-to-main hotfix. Fix is verified applied and CI is green. Scope is minimal and correct.

Template Completeness

  • [x] Type — Bug
  • [x] Lineage — discovered after merging email PRs #317, #318, #329
  • [x] Repo — forgejo_admin/basketball-api
  • [x] User Story — implicit: CI deploy pipeline must pass for superadmin deployments
  • [x] Context — root cause (3 email PRs merged with formatting violations), pipeline numbers, commit SHA
  • [x] File Targets — src/basketball_api/services/email.py
  • [x] Acceptance Criteria — 3 criteria, all checked off (retroactive)
  • [x] Test Expectations — pipeline #331 success
  • [x] Constraints — direct push to main noted, root cause identified
  • [x] Checklist — 3 items (2 checked, 1 unchecked: convention enforcement)
  • [x] Related — project and originating PRs listed

Traceability

  • [x] story:WS-S1 — "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
  • [x] story note verified — found in project-westside-basketball user-stories section (Superadmin list)
  • [x] arch:basketball-api — references the basketball-api service
  • [ ] arch note MISSING — no arch-basketball-api note found in pal-e-docs. Acceptable for a retroactive hotfix; basketball-api is a well-known repo. [SCOPE] Create architecture note arch-basketball-api.
  • [x] Forgejo issue — forgejo_admin/basketball-api#332, open

File Targets

  • [x] src/basketball_api/services/email.py — verified: file exists, ruff format --check passes clean (exit 0). All 91 repo files pass ruff format.
Targets are specific and verified. Single file, single change.

Repo Placement

OK. Issue filed on forgejo_admin/basketball-api, fix applied in basketball-api. Single repo, correct placement. No cross-repo impact.

Dependencies

  • [x] PRs #317, #318, #329 (email endpoints) — merged, caused the formatting violation
  • [x] CI pipeline #331 — passed after fix
No unresolved dependencies. All prerequisites satisfied.

Acceptance Criteria

All 3 AC are already satisfied (retroactive ticket). Each is testable:
  • "ruff format applied to email.py" — verified via ruff format --check (exit 0)
  • "CI pipeline #331 passed" — referenced in issue, verifiable via Woodpecker
  • "All 3 email endpoints deployed" — downstream of pipeline pass
Criteria are specific and agent-verifiable. No ambiguity.

Blast Radius

  • Single file formatting fix — zero functional change, zero risk of regression
  • ruff format --check passes on all 91 files in the repo (verified)
  • ruff check (lint) passes on all files (verified)
  • pre-commit config exists with ruff hooks (.pre-commit-config.yaml) — agents bypassing --no-verify caused this
  • Systemic risk: other repos with ruff CI steps could hit the same agent bypass pattern. Convention gap is the real blast radius.

Decomposition Assessment

No decomposition needed.
  • 1 discrete change (formatting fix on 1 file) — well under 3-thing limit
  • Fix already applied in seconds — well under 5-minute rule
  • No independent subtasks to parallelize

Recommendation

  • [SCOPE] Create architecture note arch-basketball-api in pal-e-docs for the basketball-api service.
  • [SCOPE] The unchecked checklist item ("Convention added: agents must run ruff format before pushing") is discovered scope. Create a separate Forgejo issue to enforce pre-commit/ruff in agent dispatch prompts or hooks. This is the systemic fix that prevents recurrence.