pal-e-docs

Review: Anthropic AI engine with tool definitions and confirmation flow

review-598-2026-03-28 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Depends on #5 (basketball client)
  • [x] Repo — forgejo_admin/westside-ai-assistant
  • [x] User Story — As Marcus (admin), natural language → basketball-api ops
  • [x] Context — Detailed: Anthropic tool_use, system prompt, confirmation state machine, GroupMe wiring
  • [x] File Targets — 3 creates, 1 modify, 2 do-not-touch
  • [x] Acceptance Criteria — 9 items
  • [x] Test Expectations — 7 items
  • [x] Constraints — SDK, model config, system prompt rules, GroupMe bot post, 1000-char limit
  • [x] Checklist — PR, tests, no unrelated changes
  • [x] Related — project page, architecture, 3 user stories

Traceability

  • [x] story:read-ops — read operations story (tool dispatch for reads)
  • [x] story:write-ops — write operations story (tool dispatch for writes)
  • [x] story:safety — safety story (confirmation flow prevents destructive ops)
  • [x] arch:A2 — AI Engine component in arch-domain-westside-ai-assistant
  • [x] Forgejo issue — forgejo_admin/westside-ai-assistant#6, state: open

File Targets

  • [x] app/ai.py (create) — does not exist yet; repo only has README.md. Valid target since #4 scaffolds the app/ directory.
  • [x] tests/test_ai.py (create) — does not exist yet. Valid, tests/ created by #4.
  • [x] tests/test_confirmation.py (create) — does not exist yet. Valid, new file.
  • [x] app/groupme.py (modify) — does not exist yet; created by #4. Valid target assuming #4 completes first.
  • [x] app/basketball.py (do-not-touch) — created by #5. Correct: consumed as dependency.
  • [x] app/config.py (do-not-touch) — created by #4. Correct: env vars already defined there.
All targets are specific enough for an agent to act on without guessing. File targets are accurate pending completion of prerequisite tickets #4 and #5.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, all file targets in same repo. No cross-repo work required.

Dependencies

  • [x] #5 (Basketball-API client) — explicit dependency in Lineage. State: open. Creates app/basketball.py consumed by this ticket. Pending.
  • [ ] #4 (FastAPI scaffold) — implicit dependency, NOT listed in Lineage. State: open. Creates app/groupme.py, app/config.py, app/__init__.py, tests/__init__.py which this ticket requires. Pending, and undocumented.
Execution order must be: #4 → #5 → #6. Both dependencies are in backlog on board-westside-ai-assistant.

Acceptance Criteria

9 ACs. Testability assessment:
  • ACs 1-5 (tool dispatch + confirmation flow) — testable via mocked Anthropic responses and mocked basketball client. Well-specified before/after behavior.
  • AC 6 (tool definitions match basketball.py exactly, 7 reads + 7 writes) — testable via introspection against basketball.py functions. Requires #5 complete to verify counts.
  • AC 7 (requires_confirmation metadata on write tools) — testable via tool definition inspection.
  • AC 8 (conversation history capped at 20 per group) — testable, clear boundary condition.
  • AC 9 (GroupMe responses are plain text, concise, no HTML/markdown) — testable for "no HTML/markdown" but "concise" is subjective. Suggest tightening: "responses contain no HTML tags or markdown syntax."
Overall: ACs are well-specified and individually testable. Count of 9 triggers decomposition threshold.

Blast Radius

  • Files touched: 3 new + 1 modified in a single repo.
  • No other services in the platform use the Anthropic SDK — zero shared-library risk.
  • The AI engine is self-contained. Only integration surface is basketball-api (consumed read-only via basketball.py client from #5).
  • GroupMe bot posting is new — no existing bot behavior to conflict with.
  • Rollback: straightforward — revert the PR, GroupMe callback falls back to logging-only behavior from #4.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:
  • Discrete changes: 4 (system prompt + tool defs, confirmation state machine, GroupMe wiring, conversation history). Exceeds 3-thing limit.
  • Acceptance criteria: 9 items. Exceeds 5-item threshold.
  • Test expectations: 7 items across 2 test files.
  • Estimated agent time: 8-12 minutes — system prompt authoring + 14 tool definitions + confirmation state machine + GroupMe wiring + 2 test files with 7+ test cases. Exceeds 5-minute rule.
The ticket covers three concerns that could be parallelized:
  • AI engine core — system prompt, 14 tool definitions, process_message(), conversation history, GroupMe response posting (ACs 1, 6, 7, 8, 9)
  • Confirmation state machine — pending action store, 5-min expiry, yes/no handling (ACs 2, 3, 4, 5)
However, both concerns share app/ai.py — confirmation is integral to process_message(). Clean split: Ticket A builds the engine with read-only dispatch (~5 min), Ticket B adds write confirmation on top (~4 min). Ticket B depends on Ticket A.
Recommend decomposition into 2 sequential tickets.

Recommendation

  • [BODY] Add explicit dependency on #4 in Lineage: "Depends on forgejo_admin/westside-ai-assistant #4 (scaffold) and #5 (basketball client)."
  • [DECOMPOSE] 9 ACs + 7 test expectations exceeds both 5-AC and 5-minute thresholds. Recommend splitting into 2 Forgejo issues: