pal-e-docs

Review: GroupMe bot registration + secrets + go-live validation

review-599-2026-03-28 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Depends on #1, #2, #3 (infra) and #6 (AI engine)
  • [x] Repo -- forgejo_admin/westside-ai-assistant + cluster ops
  • [x] User Story -- As Marcus (admin) I want the bot registered and deployed so I can start using the AI assistant
  • [x] Context -- Go-live ticket, partially manual, all code/infra must be in place first
  • [x] File Targets -- None (ops/validation ticket, explicitly states no code changes)
  • [x] Acceptance Criteria -- 6 items covering registration, secrets, pod health, and 3 functional tests
  • [x] Test Expectations -- 4 manual items + run command (manual validation in GroupMe test group)
  • [x] Constraints -- 4 constraints including GroupMe API, kubectl-only secrets, group lockdown, tofu approval gate
  • [x] Checklist -- 4 items (bot registered, secrets deployed, pod running, e2e validation)
  • [x] Related -- project-westside-ai-assistant, service-onboarding-sop steps 7-10
All template sections present and filled.

Traceability

  • [x] story:read-ops -- Marcus can query player/team/payment data via GroupMe and get accurate answers
  • [x] story:write-ops -- Marcus can update player info and manage teams via GroupMe with confirmation before writes
  • [x] story:safety -- Write ops require confirmation, dangerous ops excluded, bot locked to approved group
  • [x] arch:A1 -- Domain Model (GroupMe webhook handler receives callbacks)
  • [x] arch:A4 -- Deployment (FastAPI pod, Tailscale funnel, k8s secrets, namespace)
  • [x] Forgejo issue -- forgejo_admin/westside-ai-assistant#7, open
Traceability complete. All three project user stories covered. Two architecture components correctly referenced (A1 for the bot callback endpoint, A4 for deployment/secrets infrastructure).

File Targets

N/A -- ops/validation ticket with no code changes. Issue explicitly states "Files the agent should NOT touch: Application code (should be complete from prior tickets)." This is correct for a go-live ops ticket. No file paths to verify.
Targets are appropriately scoped: the agent acts via external APIs (GroupMe Bot API) and cluster tools (kubectl), not file modifications.

Repo Placement

OK. Issue is filed on forgejo_admin/westside-ai-assistant. Work involves external API calls (GroupMe bot registration) and cluster ops (kubectl secret creation, pod validation). No code changes to any repo. The "cluster ops" designation in the Repo field is honest about the scope. Single-repo placement is correct since this is operational, not code work.

Dependencies

  • [x] #1 (Provision infrastructure in pal-e-services) -- pending, in backlog
  • [x] #2 (Create kustomize overlay in pal-e-deployments) -- pending, in backlog
  • [x] #3 (NetworkPolicy update in pal-e-platform) -- pending, in backlog
  • [ ] #4 (FastAPI scaffold + GroupMe webhook handler) -- NOT listed in Lineage but REQUIRED. Pod cannot start (AC 3) without application code. Pending, in backlog.
  • [ ] #5 (Basketball-API client with Keycloak auth) -- NOT listed in Lineage but REQUIRED. Read/write tests (ACs 4-5) need the API client. Pending, in backlog.
  • [x] #6 (Anthropic AI engine with tool definitions) -- pending, in backlog
  • [x] Lucas tofu apply approval -- external human gate, documented in Constraints
Two undocumented dependencies found. All dependencies are in backlog -- this ticket is correctly sequenced last but its Lineage section is incomplete.

Acceptance Criteria

6 ACs total. Assessment by category:
  • AC 1 (bot registration): Specific -- names the bot name, callback URL, and group_id. Testable via GroupMe API response. Agent-executable.
  • AC 2 (k8s secret): Specific -- names the secret, namespace, and all 4 keys. Testable via kubectl get secret. Agent-executable. However, lists GROUPME_BOT_ID which does not appear in the deployment architecture diagram (arch-deployment-westside-ai-assistant). Mismatch needs resolution.
  • AC 3 (pod readiness): Specific and testable via kubectl. Agent-executable.
  • AC 4 (read test): Specific query with expected behavior. Human-only -- requires sending a GroupMe message and observing response.
  • AC 5 (write test): Specific with two-step confirmation flow. Human-only -- requires interactive GroupMe conversation.
  • AC 6 (safety test): Specific -- message from different group is ignored. Human-only -- requires sending from a non-allowlisted group.
No ambiguous "works correctly" language. All ACs are testable. However, the issue does not separate agent-executable ACs (1-3) from human-only ACs (4-6). An agent dispatched against this ticket would complete 1-3 then have no way to verify 4-6.

Blast Radius

  • Files/repos touched: 0 files, 0 repos. External API + kubectl only.
  • What could break: Incorrect callback URL means bot never receives messages. Wrong group_id means bot responds in wrong group. Missing secret keys means pod crash-loops.
  • Rollback: Straightforward -- delete bot via GroupMe API, delete k8s secret, pod stops. No persistent state changes.
  • Sibling impact: None. First GroupMe bot in platform. Namespaced secret. No shared infrastructure modified.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:
  • Discrete changes: 3 (bot registration, secret creation, pod verification). Meets three-thing limit.
  • Agent time estimate: ~3 minutes for the agent-executable portion (ACs 1-3). Within five-minute rule.
  • Parallelizable subtasks: No -- sequential dependency (register bot to get bot_id/token, create secret with those values, then verify pod).
  • Human validation: ACs 4-6 are a separate human phase after agent completes. Not parallelizable with agent work.
No decomposition needed. The agent portion fits in a single pass. The human portion is post-execution validation, not additional agent work. The issue just needs to clearly mark the handoff point.

Recommendation

  • [BODY] Fix incomplete Lineage: add #4 and #5 as dependencies. The pod cannot start (AC 3) without the FastAPI scaffold (#4), and read/write tests (ACs 4-5) require the basketball-api client (#5). Suggested text: "Depends on forgejo_admin/westside-ai-assistant #1, #2, #3 (infra), #4 (scaffold), #5 (API client), and #6 (AI engine)."
  • [BODY] Separate ACs into agent vs. human sections. Add a handoff marker after AC 3: "--- Agent handoff: ACs 1-3 complete. Human validates ACs 4-6 in GroupMe test group. ---"
  • [BODY] Reconcile AC 2 secret keys with deployment architecture diagram. AC 2 lists 4 keys (ANTHROPIC_API_KEY, GROUPME_BOT_ID, GROUPME_BOT_TOKEN, KEYCLOAK_CLIENT_SECRET) but arch-deployment-westside-ai-assistant shows only 3 (ANTHROPIC_API_KEY, GROUPME_BOT_TOKEN, KEYCLOAK_CLIENT_SECRET). Determine whether GROUPME_BOT_ID is a secret or an env config value, and update whichever source is wrong.