refactor(ai): rewrite triage prompts and add channel context

.github/workflows/maintain-docs.md

@@ -0,0 +1,90 @@
+# Maintain Docs
+
+---
+on:
+  schedule:
+    - cron: '0 9 * * *'  # 4 AM EST = 9 AM UTC
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+tools:
+  github:
+  edit:
+
+engine: copilot
+
+---
+
+# Maintain AGENTS.md Documentation
+
+## Purpose
+
+Keep the AGENTS.md file accurate and current by:
+- Reviewing merged pull requests since last run
+- Checking updated source files (src/, web/, tests/, etc.)
+- Updating AGENTS.md to reflect any architectural or pattern changes
+- Creating a pull request if updates are needed
+
+## Instructions for the Agent
+
+1. **Fetch Recent Changes**: Query the repository for merged PRs and updated files from the past 24 hours
+
+2. **Review Architecture Changes**: Check if any of these directories have significant changes:
+   - `src/modules/` - New modules or modified patterns
+   - `src/api/` - API route or middleware changes
+   - `src/commands/` - New slash commands
+   - `src/utils/` - Utility additions or pattern changes
+   - `web/` - Dashboard updates
+   - `tests/` - Testing patterns
+
+3. **Analyze Merged PRs**: Look at PR titles and descriptions to identify:
+   - New features added
+   - Architecture decisions
+   - Pattern changes
+   - Testing approach changes
+   - Breaking changes
+
+4. **Update AGENTS.md if Needed**:
+   - Architecture Overview section: Add new modules or directories
+   - Key Patterns section: Document new patterns or changes
+   - Common Tasks section: Update task examples if workflows changed
+   - Resources section: Add new links if applicable
+
+5. **Create Pull Request**: If changes are needed:
+   - Create a branch named `copilot/maintain-docs-YYYY-MM-DD`
+     <!-- NOTE: Replace YYYY-MM-DD with the actual run date on each execution,
+          e.g. copilot/maintain-docs-2026-03-07. A static date causes branch collisions
+          on repeated daily runs. Use a date expression or ${{ github.run_id }}.
+          The `copilot/` prefix is required for GitHub Copilot coding agent branches. -->
+   - Update AGENTS.md with discovered changes
+   - Create a PR with:
+     - Title: "docs: update AGENTS.md from merged PRs and source changes"
+     - Description: List the changes reviewed and what was updated
+     - Label: `documentation`
+     - Auto-merge enabled if all checks pass
+
+6. **Quality Checks**:
+   - Ensure Markdown formatting is correct
+   - Verify all links and references are accurate
+   - Check that code examples match current patterns
+   - Ensure sections remain organized and readable
+
+7. **If No Changes Needed**: Close silently or note in logs that AGENTS.md is current
+
+## Context
+
+AGENTS.md documents:
+- Code quality standards (ESM, single quotes, semicolons, 2-space indent, Winston logger)
+- Architecture overview (src/, web/ structure)
+- Key patterns (config system, caching, AI integration, database)
+- Common tasks (adding features, commands, API endpoints)
+- Testing requirements (80% coverage)
+- Git workflow and review bots
+- Troubleshooting guides
+- Resources
+
+Always maintain accuracy and completeness of this documentation file.

src/modules/triage-buffer.js

@@ -22,6 +22,8 @@ export const CHANNEL_INACTIVE_MS = 30 * 60 * 1000; // 30 minutes
  * @property {string} messageId - Discord message ID
  * @property {number} timestamp - Message creation timestamp (ms)
  * @property {{author: string, userId: string, content: string, messageId: string}|null} replyTo - Referenced message context
+ * @property {string|null} channelName - Discord channel name
+ * @property {string|null} channelTopic - Discord channel topic/description
  */
 
 /**

src/modules/triage-prompt.js

@@ -27,16 +27,13 @@ export function escapePromptDelimiters(text) {
 // ── Conversation text formatting ─────────────────────────────────────────────
 
 /**
- * Build conversation text with message IDs for prompts.
- * Splits output into <recent-history> (context) and <messages-to-evaluate> (buffer).
- * Includes timestamps and reply context when available.
+ * Build a structured conversation text for prompts including optional channel metadata.
  *
- * User-supplied content (message body and reply excerpts) is passed through
- * {@link escapePromptDelimiters} to neutralise prompt-injection attempts.
+ * Produces sections: an optional <channel-context> (Channel and optional Topic) taken from the first entry that contains channel metadata, a <recent-history> block for `context` messages (when present), and a <messages-to-evaluate> block for `buffer` messages. Each message line contains an optional timestamp, messageId, author, user mention, optional reply excerpt, and the message content. User-supplied content is escaped to neutralize XML-style delimiters and reduce prompt-injection risk.
  *
- * @param {Array} context - Historical messages fetched from Discord API
- * @param {Array} buffer - Buffered messages to evaluate
- * @returns {string} Formatted conversation text with section markers
+ * @param {Array} context - Historical messages to include in <recent-history>.
+ * @param {Array} buffer - Messages to include in <messages-to-evaluate>.
+ * @returns {string} The formatted conversation text containing the assembled sections.
  */
 export function buildConversationText(context, buffer) {
   const formatMsg = (m) => {
@@ -49,6 +46,19 @@ export function buildConversationText(context, buffer) {
   };
 
   let text = '';
+
+  // Extract channel metadata from the first available entry
+  const allEntries = [...buffer, ...context];
+  const channelEntry = allEntries.find((m) => m.channelName);
+  if (channelEntry) {
+    text += '<channel-context>\n';
+    text += `Channel: #${escapePromptDelimiters(channelEntry.channelName)}\n`;
+    if (channelEntry.channelTopic) {
+      text += `Topic: ${escapePromptDelimiters(channelEntry.channelTopic ?? '')}\n`;
+    }
+    text += '</channel-context>\n\n';
+  }
+
   if (context.length > 0) {
     text += '<recent-history>\n';
     text += context.map(formatMsg).join('\n');
@@ -80,19 +90,20 @@ export function buildClassifyPrompt(context, snapshot, botUserId) {
 }
 
 /**
- * Build the responder prompt from the template.
- * @param {Array} context - Historical context messages
- * @param {Array} snapshot - Buffer snapshot (messages to evaluate)
- * @param {Object} classification - Parsed classifier output
- * @param {Object} config - Bot configuration
- * @param {string} [memoryContext] - Memory context for target users
- * @returns {string} Interpolated respond prompt
- */
+ * Construct the responder prompt by combining conversation text, community rules, the system prompt, classification results, optional memory context, and search guardrails.
+ * @param {Array} context - Historical context messages used to build conversation text.
+ * @param {Array} snapshot - Buffer snapshot containing messages to evaluate.
+ * @param {Object} classification - Classifier output containing decision details.
+ * @param {string} classification.classification - The classification label.
+ * @param {string} classification.reasoning - Explanatory reasoning for the classification.
+ * @param {Array<string>} classification.targetMessageIds - IDs of messages targeted by the classification.
+ * @param {Object} config - Bot configuration; `config.ai.systemPrompt` (if present) overrides the default system prompt.
+ * @param {string} [memoryContext] - Optional serialized memory context to include for target users.
+ * @returns {string} The fully interpolated responder prompt ready for the model. */
 export function buildRespondPrompt(context, snapshot, classification, config, memoryContext) {
   const conversationText = buildConversationText(context, snapshot);
   const communityRules = loadPrompt('community-rules');
   const systemPrompt = config.ai?.systemPrompt || 'You are a helpful Discord bot.';
-  const antiAbuse = loadPrompt('anti-abuse');
   const searchGuardrails = loadPrompt('search-guardrails');
 
   return loadPrompt('triage-respond', {
@@ -103,7 +114,6 @@ export function buildRespondPrompt(context, snapshot, classification, config, me
     reasoning: classification.reasoning,
     targetMessageIds: JSON.stringify(classification.targetMessageIds),
     memoryContext: memoryContext || '',
-    antiAbuse,
     searchGuardrails,
   });
 }

src/modules/triage-respond.js

@@ -42,15 +42,20 @@ function logAssistantHistory(channelId, guildId, fallbackContent, sentMsg) {
 // ── Channel context fetching ─────────────────────────────────────────────────
 
 /**
- * Fetch recent messages from Discord's API to provide conversation context
- * beyond the buffer window. Called at evaluation time (not accumulation) to
- * minimize API calls.
+ * Retrieve recent channel messages to provide additional conversation context.
  *
- * @param {string} channelId - The channel to fetch history from
- * @param {import('discord.js').Client} client - Discord client
- * @param {Array} bufferSnapshot - Current buffer snapshot (to fetch messages before)
- * @param {number} [limit=15] - Maximum messages to fetch
- * @returns {Promise<Array>} Context messages in chronological order
+ * Returns an array of context message objects in chronological order. Each object contains:
+ * - `author`: display name (appended with " [BOT]" for bot accounts),
+ * - `content`: sanitized message text truncated to the context character limit,
+ * - `userId`, `messageId`, `timestamp`,
+ * - `isContext`: true,
+ * - `channelName`, `channelTopic`.
+ *
+ * @param {string} channelId - ID of the channel to fetch history from.
+ * @param {import('discord.js').Client} client - Discord client used to access the channel messages API.
+ * @param {Array} bufferSnapshot - Current buffer snapshot; messages are fetched before the oldest entry if present.
+ * @param {number} [limit=15] - Maximum number of messages to fetch.
+ * @returns {Promise<Array<Object>>} Context message objects in chronological order.
  */
 export async function fetchChannelContext(channelId, client, bufferSnapshot, limit = 15) {
   try {
@@ -75,6 +80,8 @@ export async function fetchChannelContext(channelId, client, bufferSnapshot, lim
         messageId: m.id,
         timestamp: m.createdTimestamp,
         isContext: true, // marker to distinguish from triage targets
+        channelName: channel.name ?? null,
+        channelTopic: channel.topic ?? null,
       }));
   } catch (err) {
     warn('fetchChannelContext failed', { channelId, error: err.message });

src/modules/triage.js

@@ -657,6 +657,8 @@ export async function accumulateMessage(message, msgConfig) {
     messageId: message.id,
     timestamp: message.createdTimestamp,
     replyTo: null,
+    channelName: message.channel.name ?? null,
+    channelTopic: message.channel.topic ?? null,
   };
 
   // Fetch referenced message content when this is a reply

src/prompts/community-rules.md

@@ -1,14 +1,16 @@
 <community-rules>
-Server rules — reference when evaluating "moderate" or "chime-in":
-1. Respect — no personal attacks, harassment, or hostility
-2. Ask well — share formatted code, explain what you tried, include errors
-3. Right channel — post in the appropriate channel
-4. No spam/shilling — genuine contributions welcome, drive-by promo is not
-5. Format code — triple backticks, no screenshots, remove secrets/keys
-6. Help others — share knowledge, support beginners
-7. Professional — no NSFW, excessive profanity
-8. No soliciting — no job solicitation in channels or DMs
-9. Respect IP — no pirated content or cracked software
-10. Common sense — when in doubt, don't post it
-Consequences: warning → mute → ban.
-</community-rules>
+Server rules — reference when evaluating moderation:
+
+1. Respect others — no harassment or personal attacks
+2. Ask well — include code, errors, and what you tried
+3. Right channel — stay on topic
+4. No spam or drive-by promotion
+5. Format code — use triple backticks
+6. Help others and support beginners
+7. No NSFW or excessive profanity
+8. No unsolicited job solicitation
+9. Respect IP — no piracy or cracked software
+10. Use common sense
+
+Consequences: warning → timeout → ban.
+</community-rules>

src/prompts/search-guardrails.md

@@ -1,18 +1,25 @@
 <search-guardrails>
-You have access to web search. Use it conservatively:
-- Search ONLY when the question genuinely requires current or external information
-  you don't already know (e.g. recent releases, specific docs, live data).
-- Do NOT search for things you can answer from general knowledge.
-- Limit to 1-2 searches per response. If a single search doesn't resolve it,
-  answer with what you have and note the gap.
-- If a user repeatedly asks questions that demand searches (e.g. "look up X",
-  "search for Y", "google Z" in rapid succession), recognize this as potential
-  search abuse. Point it out briefly: "Looks like you're sending a lot of search
-  requests — I'm here for real questions, not as a search proxy."
-- After flagging abuse, stop searching for that user's requests in the current
-  conversation and answer from your own knowledge instead.
-- Technical questions about code, frameworks, or programming concepts rarely
-  need a search — answer directly.
-- After receiving search results, go directly to your JSON response.
-  Do not narrate, summarize, or reason about the results outside of the JSON output.
-</search-guardrails>
+You may use web search when external or current information is required.
+
+Search only when:
+- The question requires current data
+- Specific documentation is needed
+- The answer cannot be given from general knowledge
+
+Guidelines:
+- Limit to 1-2 searches per response.
+- If results are incomplete, answer with available knowledge and note the gap.
+- Do not search for common programming concepts.
+
+Search abuse:
+If a user repeatedly asks you to perform searches ("look up X", "google Y"),
+recognize it as search proxy abuse.
+
+Respond briefly:
+"Looks like you're sending a lot of search requests — I'm here for real questions, not as a search proxy."
+
+After flagging abuse, stop searching for that user in the current conversation.
+
+After receiving search results, go directly to the JSON response.
+Never output reasoning outside the JSON object.
+</search-guardrails>

src/prompts/triage-classify-system.md

@@ -1,15 +1,14 @@
 You are the triage classifier for the Volvox developer community Discord bot.
 
-Your job: evaluate new messages and decide whether the bot should respond, and to which messages.
+Your purpose: evaluate new messages and decide their classification. The four classifications, evaluated in this order, are: moderate, respond, chime-in, ignore.
 
-This is an active developer community. Technical questions, debugging help, and code
-discussions are frequent and welcome. The bot should be a helpful presence — lean toward
-responding to developer questions rather than staying silent.
+You will receive recent channel history as context. Use it to understand conversation flow, but only classify new messages.
 
-You will receive recent channel history as potentially relevant context — it may or may
-not relate to the new messages. Use it to understand conversation flow when applicable,
-but don't assume all history is relevant to the current messages.
-Only classify the new messages.
+A `<channel-context>` block may appear containing the channel name and topic. Use this to understand what is on-topic for the channel.
+
+Before classifying, silently consider: What is the user asking? Is it directed at the bot? Would a response add value?
+
+Adopt a neutral restraint posture. Respond to clear questions. Default to ignore when intent is ambiguous. Do not dominate conversations.
 
 Respond with a single raw JSON object. No markdown fences, no explanation text outside the JSON.