pal-e-docs

Review: Replace 7 read tools with generic read-only api_get tool

review-721-2026-03-30 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, simplifies Nemo's read architecture
  • [x] Repo -- forgejo_admin/westside-ai-assistant
  • [x] User Story -- clear who/what/why for Marcus (admin)
  • [x] Context -- explains 7-tool problem, generic replacement rationale, safety constraint
  • [x] File Targets -- 2 files to modify, 3 files not to touch, all specific
  • [x] Acceptance Criteria -- 7 testable criteria
  • [x] Test Expectations -- unit + integration tests with run command
  • [x] Constraints -- GET-only, keep writes, update system prompt
  • [x] Checklist -- PR/tests/no-unrelated
  • [x] Related -- project and upstream issue referenced
All template-issue-feature sections present. Well-written issue.

Traceability

  • [ ] story:WS-S5 label -- MISMATCH. Superadmin WS-S5 is "basketball-api's database on CNPG shared cluster." Admin WS-S5 is "view registration stats on a dashboard." Neither matches this ticket's user story ("ask Nemo any question about program data without waiting for new tools"). Needs a new story or a correct story reference.
  • [x] arch:westside-ai-assistant label -- present on board item
  • [ ] arch note MISSING -- search for "arch-westside-ai-assistant" returned no results in pal-e-docs. [SCOPE] Create architecture note arch-westside-ai-assistant for the AI assistant component.
  • [x] Forgejo issue -- forgejo_admin/westside-ai-assistant#23, open

File Targets

  • [x] app/ai.py -- verified: contains exactly 7 read tool definitions (get_dashboard, list_players, get_player, list_teams, get_roster, get_subscriptions_overview, list_subscriptions) + 7 write tool definitions. Contains _execute_read_tool dispatch at line 228. All claims accurate.
  • [x] app/basketball.py -- verified: contains 7 matching read methods and 7 write methods. No generic get(path) method exists yet. Ready for modification.
  • [x] app/confirmation.py -- verified exists, correctly listed as NOT to touch.
  • [x] app/groupme.py -- verified exists via repo file listing, correctly listed as NOT to touch.
Targets are specific enough for an agent to act on without guessing.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, work targets the same repo. Single-repo change. No cross-repo coordination needed.

Dependencies

  • [x] basketball-api endpoints -- satisfied. The 7 existing endpoints are live. New endpoints (jerseys, schedules) are a downstream benefit, not a blocker.
  • [x] Keycloak service account -- satisfied. Already has admin access per the issue context.
Note: Forgejo issue #20 (read-only lockdown) in the same repo overlaps with this work. Consider closing #20 as superseded after #23 merges.

Acceptance Criteria

7 criteria, all testable by an agent:
  • "Single api_get tool replaces all 7 read tools" -- verify tool count in TOOLS list. Testable.
  • "api_get enforces GET method at code level" -- verify hardcoded method="GET". Testable.
  • "No request body is ever sent" -- verify no json= parameter in get method. Testable.
  • "System prompt lists example endpoints" -- verify SYSTEM_PROMPT content. Testable.
  • "Existing write tools + confirmation flow unchanged" -- verify write tool count and confirmation.py diff. Testable.
  • "How many players? still works" -- requires integration test or manual validation. Testable with mock.
  • "Who ordered jerseys? works if endpoint exists" -- conditional on basketball-api. Testable with mock.
All criteria are specific and verifiable. No ambiguous "works correctly" language.

Blast Radius

Low. Changes confined to 2 files in a single service. Write tools and confirmation flow explicitly preserved. The groupme.py webhook handler is unaffected. No other services consume the AI assistant's internal tool definitions. Rollback is straightforward (revert single PR).

Decomposition Assessment

2 file targets in 1 repo. 7 AC (over the 5-AC threshold). However, all criteria are tightly coupled -- they describe one atomic refactor (remove 7 read tools, add 1 generic tool, add 1 method to basketball.py). Decomposing would create artificial splits with merge-order dependencies. Estimated agent work: 3-4 minutes. No decomposition needed.

Recommendation

  • [LABEL] Fix story:WS-S5 label -- WS-S5 does not match this ticket's user story. Either create a new user story on project-westside-basketball user-stories section (e.g. "As an admin, I want to ask Nemo any question about program data so that new API endpoints are automatically accessible without code changes") and assign a new story ID, or map to an existing story that fits.
  • [SCOPE] Create architecture note arch-westside-ai-assistant for the AI assistant component in pal-e-docs.
  • [BODY] Minor: Related section references project-westside-ai-assistant but the pal-e-docs project slug is westside-basketball. Update to match.