[Bot] Make the bot self-diagnosing: /help, guild-join welcome, and real error strings instead of a generic "try again"

claude-bot commented

2026-08-25 20:42:13 +00:00

Collaborator

Impact: HIGH

Found in the August 2026 session lifecycle review (#319).

What the user experiences

A customer invites the bot to their server. There is no /help, no welcome message, no presence string, and no in-Discord discovery surface of any kind — every interactive surface is an emoji reaction, and commands sync globally so they can take up to an hour to even appear, with nothing telling the user that. Once commands do appear, /next, /quests, and /history give the exact same reply for "no campaign is bound to this Discord server" as for "a campaign is bound but nothing is scheduled" — so a customer who never wired up the campaign-to-server link gets told, forever, "No upcoming sessions are scheduled for this server," with nothing naming the actual missing configuration. And whenever the backend does return something diagnosable — like "LLM endpoint not configured. Set it in Admin → Bot Settings" — the bot discards it and shows a generic "Could not reach Quest Board right now. Please try again shortly.", presenting a permanent misconfiguration as a transient outage.

Evidence

No /help command, no on_guild_join handler, no presence/activity string, and no discord.ui views/buttons/modals anywhere in bot/ (grep confirms zero results).
bot/questboard_bot/main.py:133 — await self.tree.sync() with no guild=, meaning up to an hour before commands appear after invite, with nothing telling the user that.
bot/questboard_bot/cogs/sessions.py:72, :130, :261 — /next, /quests, /history collapse "no campaign bound to this guild" and "nothing scheduled" into one message.
bot/questboard_bot/cogs/recording.py:62-65 — the /record start unauthorised message never mentions /link, even though GET /bot/guilds/{id}/gms (webapp/backend/app/routers/bot.py:617-624) only returns GMs with a verified link, making this the most likely failure mode for a new GM.
Grep for detail in bot/questboard_bot/ finds only responses the bot itself emits — api_client calls raise_for_status() (e.g. :345) and cogs catch bare Exception, so every 4xx/5xx becomes "Could not reach Quest Board right now. Please try again shortly." (bot/questboard_bot/cogs/sessions.py:65,123,322,422), including the LLM-not-configured detail from webapp/backend/app/routers/bot.py:1139-1143.
/ask's helpful "no recordings yet" branch (sessions.py:431-436) is dead code, because the backend always returns a non-empty placeholder string (routers/bot.py:1157-1161).

Why it matters for a hosted product

A customer invites the bot, types /next, and is told nothing is scheduled — forever — with no way to learn that the actual problem is an unlinked Discord server, an unlinked GM account, or a backend setting the owner never touched. Every one of these becomes a "the bot doesn't work" support message that a better error string would have prevented.

Proposed fix

Add /help and an on_guild_join welcome post explaining the campaign-linking step. Move command sync to guild-scoped where practical, or at minimum post a "commands may take up to an hour to appear" note on join. Distinguish "no campaign bound to this guild" from "nothing scheduled" in /next, /quests, /history, naming the missing config in the former case. Have api_client parse and re-raise the backend's detail string so cogs can show it verbatim instead of the generic fallback (the audit's P19, P20).

Acceptance criteria

A /help command exists and lists all available commands with a one-line description each.
on_guild_join posts a welcome message naming the campaign-linking step.
/next, /quests, /history give visibly different messages for "no campaign bound to this guild" vs. "nothing scheduled".
The /record start unauthorised message names /link as a possible fix.
api_client surfaces the backend's detail string to the cog layer, and at least the LLM-not-configured and campaign-not-linked cases show it instead of the generic "try again" message.

**Impact: HIGH** Found in the August 2026 session lifecycle review (#319). ## What the user experiences A customer invites the bot to their server. There is no `/help`, no welcome message, no presence string, and no in-Discord discovery surface of any kind — every interactive surface is an emoji reaction, and commands sync globally so they can take up to an hour to even appear, with nothing telling the user that. Once commands do appear, `/next`, `/quests`, and `/history` give the exact same reply for "no campaign is bound to this Discord server" as for "a campaign is bound but nothing is scheduled" — so a customer who never wired up the campaign-to-server link gets told, forever, "No upcoming sessions are scheduled for this server," with nothing naming the actual missing configuration. And whenever the backend does return something diagnosable — like *"LLM endpoint not configured. Set it in Admin → Bot Settings"* — the bot discards it and shows a generic **"Could not reach Quest Board right now. Please try again shortly."**, presenting a permanent misconfiguration as a transient outage. ## Evidence - No `/help` command, no `on_guild_join` handler, no presence/activity string, and no `discord.ui` views/buttons/modals anywhere in `bot/` (grep confirms zero results). - `bot/questboard_bot/main.py:133` — `await self.tree.sync()` with no `guild=`, meaning up to an hour before commands appear after invite, with nothing telling the user that. - `bot/questboard_bot/cogs/sessions.py:72`, `:130`, `:261` — `/next`, `/quests`, `/history` collapse "no campaign bound to this guild" and "nothing scheduled" into one message. - `bot/questboard_bot/cogs/recording.py:62-65` — the `/record start` unauthorised message never mentions `/link`, even though `GET /bot/guilds/{id}/gms` (`webapp/backend/app/routers/bot.py:617-624`) only returns GMs with a *verified* link, making this the most likely failure mode for a new GM. - Grep for `detail` in `bot/questboard_bot/` finds only responses the bot itself emits — `api_client` calls `raise_for_status()` (e.g. `:345`) and cogs catch bare `Exception`, so every 4xx/5xx becomes **"Could not reach Quest Board right now. Please try again shortly."** (`bot/questboard_bot/cogs/sessions.py:65,123,322,422`), including the LLM-not-configured detail from `webapp/backend/app/routers/bot.py:1139-1143`. - `/ask`'s helpful "no recordings yet" branch (`sessions.py:431-436`) is dead code, because the backend always returns a non-empty placeholder string (`routers/bot.py:1157-1161`). ## Why it matters for a hosted product A customer invites the bot, types `/next`, and is told nothing is scheduled — forever — with no way to learn that the actual problem is an unlinked Discord server, an unlinked GM account, or a backend setting the owner never touched. Every one of these becomes a "the bot doesn't work" support message that a better error string would have prevented. ## Proposed fix Add `/help` and an `on_guild_join` welcome post explaining the campaign-linking step. Move command sync to guild-scoped where practical, or at minimum post a "commands may take up to an hour to appear" note on join. Distinguish "no campaign bound to this guild" from "nothing scheduled" in `/next`, `/quests`, `/history`, naming the missing config in the former case. Have `api_client` parse and re-raise the backend's `detail` string so cogs can show it verbatim instead of the generic fallback (the audit's P19, P20). ## Acceptance criteria - [ ] A `/help` command exists and lists all available commands with a one-line description each. - [ ] `on_guild_join` posts a welcome message naming the campaign-linking step. - [ ] `/next`, `/quests`, `/history` give visibly different messages for "no campaign bound to this guild" vs. "nothing scheduled". - [ ] The `/record start` unauthorised message names `/link` as a possible fix. - [ ] `api_client` surfaces the backend's `detail` string to the cog layer, and at least the LLM-not-configured and campaign-not-linked cases show it instead of the generic "try again" message.

claude-bot added this to the v4.3.0 - Product Surface: Navigation, Attention & Feedback milestone

2026-08-25 20:42:13 +00:00

claude-bot added the

bot

bug

labels

2026-08-25 20:42:13 +00:00

claude-bot referenced this issue

2026-09-06 00:34:01 +00:00

v4.3.0 build order: Product Surface in eight phases #514

claude-bot commented

2026-09-06 02:03:19 +00:00

Author

Collaborator

Picking this up as v4.3.0 phase 5, lane B (#514), followed by #393 and #392 on the same branch. Decisions: api_client raises a typed error carrying the backend's detail, and cogs show it verbatim for 4xx; /help, a guild-join welcome naming the linking step and the command-sync delay, and a presence string; "no campaign bound" and "nothing scheduled" become different sentences; the dead /ask branch gets an explicit signal from the backend instead of a placeholder string.

Picking this up as v4.3.0 phase 5, lane B (#514), followed by #393 and #392 on the same branch. Decisions: `api_client` raises a typed error carrying the backend's `detail`, and cogs show it verbatim for 4xx; `/help`, a guild-join welcome naming the linking step and the command-sync delay, and a presence string; "no campaign bound" and "nothing scheduled" become different sentences; the dead `/ask` branch gets an explicit signal from the backend instead of a placeholder string.

claude-bot referenced this issue

2026-09-06 02:23:52 +00:00

v4.3.0 build order: Product Surface in eight phases #514