feat: learn from user label actions as AI classification hints

[gentlemandev]

Summary

Capture user label add/remove events from Gmail webhooks as sender classification feedback, injected as context hints into the AI rule-selection prompt. When a user drags an email into a folder in their mail client, that classification signal improves future AI decisions for that sender.

TLDR: The webhook pipeline already receives label events but drops non-SPAM ones. This PR records them and shows them to the AI as advisory context (not hard rules), enabling the system to learn from user behavior — especially for split senders like Amazon that send both receipts and marketing.

• New SenderClassification model stores individual events with threadId/messageId for auditability
• Subjects fetched at prompt time via batch Gmail API — no email content stored in DB (privacy)
• Self-labeling filter: skips when Inbox Zero applied the same label, records user reclassifications
• Conversation-tracking rules (To Reply, Awaiting Reply, FYI, Actioned) excluded via existing shouldLearn config
• Unique constraint prevents duplicate rows from webhook retries
• Extracted shared GMAIL_SYSTEM_LABELS constant and findRuleByLabelId helper to reduce duplication
• fetchSenderFromMessage shared helper deduplicates ~30 lines of identical error handling

Test plan

• Verify label-add webhook for non-SPAM labels creates SenderClassification rows
• Verify SPAM label-add still triggers cold email learning (unchanged behavior)
• Verify self-labeling filter: system-applied labels are not recorded as classification feedback
• Verify label-removal records LABEL_REMOVED classification alongside existing exclusion GroupItem
• Verify AI prompt includes sender classifications when they exist for the sender
• Verify AI prompt is unmodified when no classifications exist
• Verify conversation-tracking rules (TO_REPLY, FYI, etc.) are excluded from feedback
• Verify webhook retry deduplication via unique constraint

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
inbox-zero	Ignored	Preview	Mar 23, 2026 10:15am

[cubic-dev-ai]

4 issues found across 10 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/web/prisma/schema.prisma">

<violation number="1" location="apps/web/prisma/schema.prisma:690">
P3: Remove the redundant `@@index([emailAccountId, sender])` because it is already covered by the composite unique index.

(Based on your team's feedback about avoiding redundant indexes when a unique constraint already provides the same indexing.) [FEEDBACK_USED]</violation>
</file>

<file name="apps/web/utils/rule/sender-classification.ts">

<violation number="1" location="apps/web/utils/rule/sender-classification.ts:130">
P2: Escape subject and rule name before injecting them into the XML-like prompt block.</violation>

<violation number="2" location="apps/web/utils/rule/sender-classification.ts:164">
P1: Avoid ambiguous `findFirst` for label-to-rule mapping; handle multiple matches explicitly to prevent misclassification.</violation>
</file>

<file name="apps/web/app/api/google/webhook/process-label-added-event.ts">

<violation number="1" location="apps/web/app/api/google/webhook/process-label-added-event.ts:180">
P1: The self-labeling check is too broad: any past system-applied label on the message causes future user re-adds of that label to be skipped.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: Avoid ambiguous findFirst for label-to-rule mapping; handle multiple matches explicitly to prevent misclassification.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/utils/rule/sender-classification.ts, line 164:

<comment>Avoid ambiguous `findFirst` for label-to-rule mapping; handle multiple matches explicitly to prevent misclassification.</comment>

<file context>
@@ -0,0 +1,176 @@
+  labelId: string;
+  emailAccountId: string;
+}) {
+  return prisma.rule.findFirst({
+    where: {
+      emailAccountId,
</file context>

[gentlemandev]

This is consistent with the existing codebase pattern — process-label-removed-event.ts uses the same findFirst query for the same label-to-rule lookup. In practice, a labelId maps to a single rule because each rule creates/owns its label. If multiple rules ever share a label, both the existing and new code would need updating.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[cubic-dev-ai]

P1: The self-labeling check is too broad: any past system-applied label on the message causes future user re-adds of that label to be skipped.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/app/api/google/webhook/process-label-added-event.ts, line 180:

<comment>The self-labeling check is too broad: any past system-applied label on the message causes future user re-adds of that label to be skipped.</comment>

<file context>
@@ -152,3 +154,73 @@ export async function handleLabelAddedEvent(
+  if (!isEligibleForClassificationFeedback(rule.systemType)) return;
+
+  // Self-labeling filter: skip if Inbox Zero already applied this label
+  const systemApplied = await wasLabelAppliedBySystem({
+    messageId,
+    emailAccountId,
</file context>

[gentlemandev]

This is an intentional trade-off. The scenario (system applies label → user removes → user re-adds same label) is rare, and the LABEL_REMOVED event from step 2 already captures the user's disagreement. Without the filter, every system-applied label would create a feedback row, creating a self-reinforcing loop where the AI's own decisions inflate the classification counts — which is much worse.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[cubic-dev-ai]

P2: Escape subject and rule name before injecting them into the XML-like prompt block.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/utils/rule/sender-classification.ts, line 130:

<comment>Escape subject and rule name before injecting them into the XML-like prompt block.</comment>

<file context>
@@ -0,0 +1,176 @@
+  const lines: string[] = [];
+
+  for (const classification of classifications) {
+    const ruleName = classification.rule?.name ?? "Unknown";
+    const subject = subjects.get(classification.messageId);
+
</file context>

[gentlemandev]

The existing codebase already injects raw email subjects and body content into LLM prompts without escaping (see stringifyEmail in ai-choose-rule.ts). The PROMPT_SECURITY_INSTRUCTIONS handle prompt injection concerns at the model level. Adding escaping here would be inconsistent with the rest of the prompt construction and wouldn't provide additional security since these XML-like tags are LLM prompt structure, not parsed by an XML processor.

[cubic-dev-ai]

Thanks for the feedback! I've updated an existing learning with this new information.