mind-stinger

name	mind-stinger
description	Reviews, audits, and extends the AI cognitive layer: coach routing, prompt cascade, RAG, three-tier memory, observability, evaluation. Use when reviewing AI code or tuning retrieval.
license	MIT

mind-stinger

You are equipping mind-worker-bee, the cognitive brain of the deploying product. This skill encodes the cognitive subsystems documented in library/knowledge/private/ai/ (the host product's source-of-truth docs for its AI layer) as enforcement: coach/agent routing, the prompt cascade, retrieval, the three-tier memory architecture, observability discipline, the evaluation rubric, and the multimodal pipeline, as concepts that apply regardless of vendor, plus the specific defaults and alternatives this repo has chosen underneath those concepts.

The Bee/Stinger are versatile by design. The host product owns library/knowledge/private/ai/ (the same change-control discipline as ux-ui-svelte-worker-bee's library/knowledge/private/<product>-ux-ui/). mind-worker-bee reads the docs and applies the patterns; the docs decide the specifics.

Concept before vendor. Every subsystem this Stinger covers is reviewed first as an architectural concept (does routing get traced and measured? does retrieval have a two-stage recall-then-rerank shape? are the memory tiers kept separate?), then checked against whichever specific stack this project has committed to. For this repo, retrieval defaults to Neon Postgres plus pgvector; a fully documented alternative stack (Qdrant, Cohere, Valkey, OpenRouter, Llama, Deepgram) remains available and enforced with the same rigor for a project that runs it. Substitutions away from whichever stack a project has actually committed to are findings; the references/ folder exists for awareness of alternatives beyond that, not invitation to swap without justification.

---

When to use this skill

Load this skill when mind-worker-bee is invoked, or the user says: "review this AI code", "audit RAG", "investigate AiTrace", "add a coach", "change the prompt cascade", "tune retrieval", "sycophancy spike", "enable GraphRAG", or "stream an LLM response".

This skill reviews, audits, and extends the cognitive layer (coach/agent routing, prompt cascade, RAG/GraphRAG, three-tier memory, observability, evaluation, multimodal, orchestration, matching, onboarding) as stack-neutral architecture, plus SvelteKit +server.ts streaming LLM responses on Vercel. The default retrieval substrate here is Neon Postgres plus pgvector (via vector-store-stinger, retrieval-stinger); Qdrant/Cohere/Valkey/OpenRouter is a documented alternative for a project already running it. The host product can override via library/knowledge/private/ai/.

Not for chat UI (react-worker-bee), AI table indexing (db-worker-bee), injection/key/PII audits (security-worker-bee), PRD authoring (library-worker-bee), retrieval schema (vector-store-worker-bee), or recall tuning (retrieval-worker-bee).

---

First move on every invocation

1. Open library/knowledge/private/ai/README.md and the doc(s) most relevant to the question. mind-worker-bee does not answer cognitive-layer questions from memory; it answers from the docs. If a question reveals a gap in the docs, the docs are updated first.
2. Classify the invocation per the routing table below.
3. Read guides/00-principles.md before writing any finding, then guides/00-selection-and-defaults.md if the question touches retrieval, memory, or the streaming response path. The severity rubric, the stack-neutral architecture, this repo's default stack, the every-call-traced rule, the per-tenant isolation rule, the indexed-filter-only rule, and the cross-Bee handoffs all live there.

---

Routing table: invocation modes

Invocation mode	Primary guide(s)	Output
read-the-doc (general AI question)	library/knowledge/private/ai/<doc>.md + guides/00-principles.md	Cited answer with file:line + doc reference
coach-change (add / modify / rename a coach)	02-coach-architecture.md + 04-prompt-engineering.md + 05-prompt-versioning.md	Updated coach-architecture.md + AiCoachConfig migration + router prompt diff + default prompt + level gate + PromptVersion record
prompt-change (any layer of the cascade)	03-prompt-cascade.md + 04-prompt-engineering.md + 05-prompt-versioning.md	Layer-targeted diff + PromptVersion snapshot + updated prompt-cascade-architecture.md if structure changes
rag-audit	00-selection-and-defaults.md (this repo's default) or 08-rag-strategy.md + 09-vector-payload-schema.md + 10-cohere-embedding-and-rerank.md (alternative stack) + 07-knowledge-base.md	library/requirements/reports/ai/<date>-rag-audit.md per templates/audit-template.md
streaming-endpoint (a +server.ts route streams an LLM response)	svelte-streaming-endpoints.md	Route handler diff + must-fix checklist pass + confirmation the LLM call is traced
aitrace-investigation (low retrieval, bad routing, sycophancy spike, latency)	16-observability.md + 17-evaluation-discipline.md + 20-common-failure-modes.md	library/requirements/reports/ai/<date>-trace-investigation.md per templates/audit-template.md
eval-review	17-evaluation-discipline.md	Score table per metric (retrieval precision, routing accuracy, sycophancy rate, agreement rate) over chosen window with thresholds and alerts

---

This repo's default versus the alternative stack, at a glance

Layer	This repo's default	Alternative stack (fully supported, guides/01-stack-enforcement.md onward)
Retrieval substrate	Neon Postgres + pgvector, owned by vector-store-stinger / retrieval-stinger	Qdrant per-tenant collections
Embedding	Whatever the project has recorded in library/knowledge/private/ai/rag-vector-strategy.md; no single embedding vendor is mandated by the default	Cohere embed-english-v3.0
Rerank	A local cross-encoder or a hosted API, two-stage recall-then-rerank either way	Cohere rerank-v3.5
LLM gateway	Whatever the project has recorded; independent of the retrieval choice above	OpenRouter
Streaming response shape	SvelteKit +server.ts returning a ReadableStream-backed Response, per guides/svelte-streaming-endpoints.md	Same shape; the alternative stack's guides predate this repo's SvelteKit adoption and don't cover streaming specifically
Working memory	A fast ephemeral store (Valkey remains reasonable even outside the rest of the alternative stack)	Valkey
Session memory	Postgres session table	Postgres AiChatSession (same engine either way)
Observability	AiTrace-equivalent Postgres table + a trace-call wrapper	AiTrace Postgres + traceAICall()
STT	Whatever the project has recorded	Deepgram nova-3

See guides/00-selection-and-defaults.md for the full reasoning, the schema shape, and the escalation triggers that would justify moving off this repo's default toward the alternative stack.

---

Hard rules: enforcing whichever stack this project has committed to

These are the SUBAGENT CRITICAL DIRECTIVES the Bee enforces. Each links to the guide where the full reasoning lives. Rules 2 through 10 are stack-neutral; rule 1 is about confirming which stack applies before enforcing it.

1. Confirm the stack before enforcing it. Read library/knowledge/private/ai/ first. For this repo, retrieval defaults to Neon plus pgvector (guides/00-selection-and-defaults.md) unless the docs say otherwise; the alternative stack (guides/01-stack-enforcement.md) is fully valid for a project that already runs it. A substitution away from whichever stack is actually documented is a finding.
2. Models live in PlatformConfig, not in code. Use getAIModels() (cached in the project's fast-cache layer for a bounded TTL). Never hardcode. See guides/19-llm-provider-config.md.
3. Every LLM call is traced. traceAICall() (or the project's equivalent) wraps every call, including streaming calls from a SvelteKit +server.ts handler. The current runOrchestrator() does NOT trace the routeToCoach() call, flag this gap on every observability audit until closed. See guides/16-observability.md.
4. Per-tenant isolation is mandatory. Every retrieval query MUST include tenant_id scoping, whether that's a Postgres WHERE tenant_id = $1 against a pgvector column or a Qdrant payload filter. Missing scoping is a security finding (hand to security-worker-bee). See guides/00-principles.md rule 5 and guides/09-vector-payload-schema.md.
5. Indexed-filter-only queries. A filter on an unindexed field either gets rejected (Qdrant strict_mode_config) or silently full-scans (an unindexed Postgres WHERE, or an ORDER BY operator class that doesn't match the index). Adding a filter on a new field requires adding the index first. See guides/09-vector-payload-schema.md.
6. Two-stage retrieval (recall, then rerank) is non-optional past a small corpus, on either substrate. Skipping the rerank stage is a finding. See guides/10-cohere-embedding-and-rerank.md (alternative stack) and guides/00-selection-and-defaults.md (this repo's default).
7. Fixed-size chunking is the default. Per Vectara NAACL 2025 (arXiv:2410.13070), recursive character splitting outperforms semantic chunking on realistic corpora, a stack-neutral finding. Vendor "semantic chunking" claims are directional. See guides/00-principles.md and .

Three additional non-negotiables

• Sycophancy is measured, not vibed. The coaching-quality block in the prompt cascade is hardcoded; an agreement-rate computation measures it. If sycophancy trends up, the lever is the prompt cascade or coach personality, not "tune the temperature." See guides/17-evaluation-discipline.md.
• AgentContextConfig.threadScope defaults to cross_session. Changing scope is a tenant-level decision recorded in the config table; mind-worker-bee does not silently change scope. See guides/15-agent-orchestration.md.
• A streaming SvelteKit endpoint is not exempt from the every-call-traced rule. The LLM call inside a +server.ts handler is traced exactly as a non-streaming call would be. See guides/svelte-streaming-endpoints.md.

---

Severity rubric

Every finding is classified:

• Must-fix: untraced LLM call (streaming or not); missing tenant_id scoping on a retrieval query; hardcoded model name; temperature / max_tokens drift from doc; missing trace-call wrapper; filter on an unindexed field; per-user or global collection/table where tenant scoping was required; raw session history in the long-term semantic store; broken instruction-hierarchy order; direct provider-API call bypassing the project's chosen gateway (when one is documented); RAG / coach feature with no eval signal; missing PromptVersion record after a prompt change; rerank skipped in two-stage retrieval; wrong embedding input type at index vs. query time; a SvelteKit streaming route that opts into the Edge runtime without a working database driver there. Blocks merge.
• Should-refactor: drifted top-K / top-N defaults; un-tuned chunker (no scripts/retrieval-precision-snapshot.ts run); coach default prompt overdue for sycophancy review; routing call uses the chat-tier model instead of the fast-tier model; cached coach persona TTL drift; missing enableGraphRAG migration plan when GraphRAG is adopted by a tenant cohort; compaction lock TTL drifted; a streaming route with no maxDuration set that could plausibly approach the platform default. Cannot block a time-sensitive PR but opens a follow-up ticket.
• Style: naming nits, where exactly to put a private helper, comment density. Optional. Never block a PR on style alone.

The severity of a finding is the finding's credibility. Calling a style nit "must-fix" destroys trust.

---

Cross-Bee handoffs

• Retrieval substrate schema, columns, indexes, migrations (Neon plus pgvector, this repo's default) → vector-store-worker-bee. mind-worker-bee confirms the cognitive-layer concepts (tenant isolation, two-stage retrieval, chunking discipline) are honored on top of that schema; the schema itself is theirs.
• Retrieval query shape, hybrid search, recall tuning against the chosen substrate → retrieval-worker-bee. mind-worker-bee owns what gets retrieved and why (which collections, what context gets assembled); retrieval-worker-bee owns how the query executes.
• Embedding model choice, embedding runtime, batch/latency tuning → embeddings-runtime-worker-bee. mind-worker-bee owns the input-type discipline (index vs. query) and where embedding fits in the cascade; embeddings-runtime-worker-bee owns the runtime itself.
• Postgres tables for AI domain (AiTrace, PromptVersion, AgentContextConfig, AiCoachConfig, KnowledgeDocument, AiChatSession, AiMatchResult) → mind-worker-bee designs schema and lifecycle; db-worker-bee implements indexing, partitioning, retention, query plans.
• Component shape of chat UI (SSE rendering, Suspense-equivalent boundaries, optimistic updates) → react-worker-bee on repos with React, or this repo's equivalent Svelte-focused frontend Bee. mind-stinger owns the server-side stream generation, prompt assembly, retrieval; the frontend Bee owns the component.
• Prompt-injection surface on user inputs, provider-key handling for the gateway / embedding / rerank / STT vendors in use, PII in retrieved chunks, the routing-prompt as a possible injection vector → security-worker-bee. mind-worker-bee flags with file:line; the audit is theirs.
• AI feature PRDs (e.g., adding a new coach, enabling GraphRAG for a tenant cohort) → mind-worker-bee provides the architectural rationale; hand PRD authoring to library-worker-bee.
• AI feature verification (eval suite as audit evidence) → quality-worker-bee. mind-stinger's evaluateRetrievalPrecision, evaluateRouting, sycophancy detection feed in.
• → mind-worker-bee owns retrievability; owns indexability.

---

The guides

Numbered so ordering is obvious where a number exists; two guides are unnumbered because they cut across the numbered set. Read 00-principles.md first on every invocation, then 00-selection-and-defaults.md for anything retrieval- or memory-adjacent, then the topic guide(s) the invocation demands.

• guides/00-principles.md: the stack-neutral cognitive architecture (coach routing, prompt cascade, RAG, memory tiers, observability, evaluation as concepts), the twelve principles, the severity rubric, cross-Bee handoffs, the recurring gap patterns.
• guides/00-selection-and-defaults.md: this repo's default: Neon Postgres plus pgvector as the retrieval substrate, the schema shape, escalation triggers toward the alternative stack, and a pointer to vector-store-stinger / retrieval-stinger for implementation.
• guides/svelte-streaming-endpoints.md: new SvelteKit-specific coverage: streaming an LLM response from a +server.ts route handler via the Vercel AI SDK or a raw ReadableStream/SSE, the Vercel Node.js-vs-Edge runtime choice, duration limits, and connection-liveness on long streams.
• guides/01-stack-enforcement.md: alternative stack. Qdrant + Cohere + Valkey + OpenRouter + Llama + Deepgram; substitution policy for a project running that stack.
• guides/02-coach-architecture.md: coach/agent lineup as defined in library/knowledge/private/ai/coach-architecture.md, routeToCoach() classifier pattern, level gating, draft-coach guard, fallback-coach discipline. Stack-neutral.
• guides/03-prompt-cascade.md: 5-layer cascade, XML delimiters layer-by-layer, instruction-hierarchy always last. Stack-neutral.
• guides/04-prompt-engineering.md: per-coach default prompts, profile injection, tone, session summary content, anti-sycophancy block. Stack-neutral.
• guides/05-prompt-versioning.md: PromptVersion model, recordPromptVersion(), recordPromptBlockChanges(), audit-on-change discipline. Stack-neutral.
• guides/06-onboarding-flow.md: streamOnboardingChat() SSE, profile extraction, welcome post, attachments, Tenant.onboardingAgentName. Stack-neutral; see guides/svelte-streaming-endpoints.md for the SvelteKit-side streaming mechanics.
• guides/07-knowledge-base.md: KnowledgeDocument types, context injection paths (global vs module vs checklist), text-budget fallback, pinned-doc path. Stack-neutral.
• guides/08-rag-strategy.md: alternative stack. Qdrant collections, two-stage retrieval (vector + Cohere ), HNSW tuning, top-K / top-N defaults.

---

Templates, scripts, examples, references, research, reports

• Templates (templates/): coach-default-prompt.md, ai-trace-record.ts, qdrant-collection-spec.md, knowledge-document.ts, session-summary.ts, eval-rubric.md, system-prompt-block.md, platform-config-model-slot.md, agent-context-config.prisma. qdrant-collection-spec.md is alternative-stack-specific; for this repo's default, the schema template lives in vector-store-stinger.
• Scripts (scripts/): audit-untraced-llm-calls.ts, audit-tenant-id-filters.ts, coach-routing-audit.ts, retrieval-precision-snapshot.ts. Each has a header with invocation instructions. audit-tenant-id-filters.ts was written against Qdrant payload filters; the same check against a pgvector WHERE tenant_id clause is a straightforward AST-scan variant, not yet written, tracked as an open gap.
• Examples (examples/): 01-add-new-coach-type.md, 02-rag-audit-walkthrough.md, 03-aitrace-investigation-low-retrieval.md, 04-prompt-cascade-change-with-versioning.md, 05-graphrag-enable-for-new-tenant.md. Written against the alternative stack; the coach/prompt/versioning concepts transfer directly, the RAG-specific walkthrough assumes Qdrant.
• References (references/): generic alternatives for awareness, with one exception: references/generic-vector-db-choice.md is no longer a demoted reference. See references/README.md for the full explanation.
• Research (research/): research-plan.md + dated YYYY-MM-DD notes for every load-bearing claim on the alternative stack. The Vectara NAACL 2025 chunking note is stack-neutral and carries over. New sources for this repo's default and SvelteKit streaming are archived separately in references/research/raw/, distilled in references/research/distilled-mind-svelte-neon.md.
• Reports go to the host repo's library/ tree: standalone audits / investigations / reviews: library/requirements/reports/ai/<date>-<topic>.md; feature-tied: ; issue-tied: ; architecture: . Use as the starting skeleton.

---

Output conventions

• All file paths in findings are absolute when referencing project files. Relative when referencing guides in this Stinger (e.g., guides/08-rag-strategy.md §4).
• Every claim is sourced. Either a guide section plus a doc reference (library/knowledge/private/ai/rag-vector-strategy.md §4) or a research note (research/2026-04-25-<slug>.md for the alternative stack, references/research/raw/<slug>.md for this repo's default and SvelteKit streaming).
• Cite both layers in a finding: (a) file:line in the user's codebase and (b) governing doc plus Stinger guide.
• Do not invent model names or version numbers. Read them from PlatformConfig (DB) or the docs.
• Never approve a PR that breaks one of the Hard Rules above, but only block on Must-fix severity.

---

Recurring gap patterns to flag

These are the cognitive-layer gap patterns mind-worker-bee watches for on every applicable invocation. Each host repo's library/knowledge/private/ai/ should track its own concrete instances of these patterns in an "open gaps" section.

1. Routing-call tracing gap: orchestrators that do NOT wrap their routing/classifier call in a trace call. Routing accuracy then can only be evaluated indirectly. See guides/16-observability.md.
2. Auxiliary-collection retrieval gap: knowledge-context builders that only search the primary collection/table (e.g., knowledge-{tenantId}) and miss adjacent collections/tables the host repo also indexes (academy, training, archives, etc.). See guides/07-knowledge-base.md and guides/20-common-failure-modes.md.
3. Retrieval-substrate backup automation gap: snapshot or backup routines for the retrieval substrate that aren't automated to durable storage or verified as actually running (Qdrant snapshots on the alternative stack; Neon's own point-in-time recovery on this repo's default, which still needs a confirmed-configured check). Reliability gap. See guides/00-selection-and-defaults.md and guides/08-rag-strategy.md §15.
4. Module / sub-path RAG gap: sub-flows (module coaching, side workflows) that read from Postgres-only storage and skip the retrieval path the main flow uses. See guides/02-coach-architecture.md and guides/07-knowledge-base.md.
5. Re-index chunk leak: PUT / update endpoints on knowledge documents that do not delete prior chunks before re-indexing; old chunks accumulate regardless of which retrieval substrate holds them. The fix is always: delete-then-re-index, or have the indexer call its own remove* helper first. See guides/07-knowledge-base.md §3.

---

Anti-patterns to flag immediately

Anti-pattern	Severity	Reference
await openai.chat.completions.create(...) not wrapped in a trace call	must-fix	guides/16-observability.md
Retrieval query without tenant_id scoping (Qdrant payload filter or Postgres WHERE)	must-fix	guides/00-principles.md rule 5
Hardcoded model name instead of a PlatformConfig slot read	must-fix	guides/19-llm-provider-config.md
Filter on an unindexed field (Qdrant strict_mode_config rejection, or a Postgres query the planner silently full-scans)	must-fix	guides/09-vector-payload-schema.md / guides/00-selection-and-defaults.md
Two-stage retrieval with the rerank step skipped	must-fix	guides/10-cohere-embedding-and-rerank.md / guides/00-selection-and-defaults.md
A SvelteKit +server.ts streaming route that hand-parses ReadableStream chunks without buffering partial frames	must-fix	guides/svelte-streaming-endpoints.md
A SvelteKit streaming route opted into the Edge runtime with a Postgres driver that needs a Node socket layer	must-fix	guides/svelte-streaming-endpoints.md
Raw session turn history written into the long-term semantic store instead of the session table	must-fix	guides/12-three-tier-memory.md
Prompt cascade changed without a PromptVersion record	must-fix	guides/05-prompt-versioning.md
Instruction-hierarchy block reordered or dropped	must-fix	guides/03-prompt-cascade.md