Skip to content

feat(quick-help): explicit serviceLabels for RAG retriever filtering

Jérôme Revillard requested to merge feat/quick-help-service-labels into main

What

Quick Help buttons + sidebar selections sent localized titles as the retriever filter label → matched zero chunks (6/7 el-salvador Quick Help buttons returned 0 docs; sidebar broke for all non-English locales).

Fix

Decouple display (localized title) from filter (English KB labels):

  • New config fields: serviceLabels (English KB labels array) + hidden (no-corpus buttons)
  • serviceKey repurposed as the stable English key for the retriever filter
  • Query-build uses serviceLabels array → serviceKey fallback (never the localized service)

Layers

  • FE (Vue): loadQuickHelpButtons, selectQuickHelpOption (replace-previous), query-build flatMap, getCategoryLabelById (null, was Category NN), checkContextConfig (blocks all users, aborts sendMessage), removeContextItem
  • Mobile (Flutter): _activeServiceLabels field, _quickHelpPressed (sets labels + clears sidebar), _sendStreaming gating + context block, labels persist across multi-turn (web parity)
  • Backend: preserve null categoryLabel (was || General)
  • ChatQnA: extracted _build_filter_labels pure helper — singular/plural categoryLabel coercion + dedup + non-string guard (was plural-only → category filter was dead)
  • i18n: noFilterWarning key added to all 14 locales

Tests

  • FE: +9 unit tests (85 pass) — hidden filter, serviceLabels read, replace-previous, sidebar additive, getCategoryLabelById null, checkContextConfig block conditions, query-build flatMap
  • Python: +12 (test_build_filter_labels) — singular/plural/mixed/empty/dedup/coercion
  • Backend: +3 (null-preserve, missing-default-null, valid-pass-through)
  • All lint + format green; flutter analyze clean

Adversarial review (blind + edge-case + acceptance auditors)

8 patches applied post-review (display decoupling, mobile persistence, dedup, coercion guard, i18n key, null just-chat, sidebar-clear on Quick Help), 3 deferred (logged in deferred-work.md: localized categoryLabel under AND strategy, non-streaming mobile, 2 missing tests), 3 rejected.

Full spec: _bmad-output/implementation-artifacts/spec-quick-help-service-labels.md (status done, with Suggested Review Order).

Out of scope (follow-up)

  • el-salvador config migration (separate MR on el-salvador-contextual: patch 3 buttons, hide 4, fix mobile stale 26653264)
  • Backend categoryId→nameEN resolution (deferred — benign under OR strategy)

Merge request reports