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
memory-refactor (working / session / long-term tier change)	12-three-tier-memory.md + 13-context-continuity.md	ADR at library/knowledge/private/architecture/ADR-<n>-<topic>.md + phased migration plan
orchestration-change (runOrchestrator(), assembleContextPacket(), AgentContextConfig)	15-agent-orchestration.md + 16-observability.md	Updated agent-orchestration.md + orchestrator diff + context-packet diff + AgentContextConfig migration
multimodal-extension (image / video / audio path)	14-multimodal-pipeline.md + 09-vector-payload-schema.md	Updated multimodal-media-pipeline.md + processor diff + media payload/schema diff
graphrag-enable / extend (gated path)	11-graphrag.md	Updated graphrag-knowledge-graph.md + graph-retriever.ts diff + RRF weight justification
matching-tweak (runLLMMatching(), scoring, caching)	18-matching.md	Diff to matching prompt + AiMatchResult migration if shape changes
onboarding-flow (streamOnboardingChat(), profile extraction, welcome post)	06-onboarding-flow.md	Diff to onboarding agent + tenant display name change + tool handler diff

---

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 research/2026-04-25-vectara-naacl-2025-chunking.md.
8. Three-tier memory boundaries are load-bearing. Working (ephemeral, TTL) → session summary (Postgres, durable, structured) → long-term (the project's retrieval substrate, semantic / relational). Don't mix tiers. See guides/12-three-tier-memory.md.
9. Turn-count compaction with a lock. appendTurnAndMaybeCompact() (or the project's equivalent) triggers at 40 turns under a session-scoped lock (NX, EX 600). Adjusting the threshold requires updating context-continuity.md and a measured eval pass. See guides/13-context-continuity.md.
10. The instruction-hierarchy block is always last. It declares which earlier instructions win on conflict. Reordering or removing it breaks override discipline. See guides/03-prompt-cascade.md.

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.
• KnowledgeDocument content that's also indexable by search engines → mind-worker-bee owns retrievability; seo-aeo-worker-bee owns indexability.
• Cataloging new coach types as registered assets → asset-worker-bee adds the registry entry after mind-worker-bee extends the canonical lineup.

---

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 rerank-v3.5), HNSW tuning, top-K / top-N defaults.
• guides/09-vector-payload-schema.md: alternative stack. Payload fields per Qdrant collection, COMMON_INDEXES, strict_mode_config: { enabled: true }.
• guides/10-cohere-embedding-and-rerank.md: alternative stack. embed() / embedQuery() / rerank() patterns, batch sizing (96/req), input-type discipline, latency targets.
• guides/11-graphrag.md: alternative stack, Qdrant-adjacent. GraphEntity / GraphRelationship, graph-retriever.ts, findRelevantEntities(), traverseGraph(), RRF fusion via rrf.ts, feature-flag gating.
• guides/12-three-tier-memory.md: alternative stack for the storage engines; the tier concept is stack-neutral. Valkey working / Postgres session / Qdrant + graph long-term, generateSessionSummary(), temporal decay (memory-decay.ts).
• guides/13-context-continuity.md: session state machine, 40-turn compaction with a lock, reconstructSession(), TTL discipline. Stack-neutral.
• guides/14-multimodal-pipeline.md: image / video processors, Deepgram STT, media collection/table, MediaSummarizer recursive map-reduce.
• guides/15-agent-orchestration.md: runOrchestrator(), assembleContextPacket() parallel I/O, AgentContextConfig thread-scope policy. Stack-neutral.
• guides/16-observability.md: AiTrace schema, traceAICall() fire-and-forget, every-call-traced rule, the routing-call gap. Stack-neutral.
• guides/17-evaluation-discipline.md: evaluateRetrievalPrecision(), evaluateRouting(), sycophancy detection, computeAgreementRate(), targets and alert thresholds. Stack-neutral.
• guides/18-matching.md: runLLMMatching(), complementarity scoring, AiMatchResult, caching strategy. Stack-neutral.
• guides/19-llm-provider-config.md: alternative stack. OpenRouter setup, PlatformConfig model slots, getAIModels() cache, switching models procedure.
• guides/20-common-failure-modes.md: recurring cognitive-layer issues (issue #46 academy retrieval, untraced router call, drift between cached coach persona and DB, missing tenant scoping, temperature/max_tokens drift, sycophancy creep). Stack-neutral.

---

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: library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-<type>-report.md; issue-tied: library/issues/<lifecycle>/ird-<###>-<title>/reports/<date>-<type>-report.md; architecture: library/knowledge/private/architecture/ADR-<n>-<topic>.md. Use templates/audit-template.md as the starting skeleton.

---

Output conventions