Dashboard/Algolia-Central/Documentation/05-Prompts-Reference.md
Algolia-Central

Documentation/05-Prompts-Reference.md

05 — Prompts Reference

Last updated: 2026-04-17. Where every LLM prompt lives.

Map: Where Prompts Live

Persona / purpose File / source Who loads it Used by
Signal Extractor ("Brain") lib/search/prompts/brain.ts getBrainPrompt(currentDate) signal_extractor.extractSignals
Maverick (AE) lib/search/prompts/maverick.ts + config/system/PERSONAS.md buildMaverickPromptWithPersona + loadPersonaDefinition streamMaverickResponse
Elena (SE) Agent Studio UI — NOT IN GIT Agent Studio runtime callAgentStudio({agentId: 'f029acbb-...'})
Bruno (Architect) Agent Studio UI — NOT IN GIT Agent Studio runtime callAgentStudio({agentId: 'facb549e-...'})
Integrity audit lib/search/prompts/integrity.ts getIntegrityAuditPrompt [UNVERIFIED — likely DEAD after Step 2]
Fallback / Casual / Consultant / Squad / Support / SE (legacy) lib/search/prompts/{fallback,casual,consultant,squad,support,se}.ts various [UNVERIFIED — likely LEGACY from RC1]

Active Prompts (in-repo)

1. Brain / Signal Extractor

File: lib/search/prompts/brain.ts Version constant: BRAIN_PROMPT_VERSION = "8.5.1-maverick-rc2-unified" (line 8) Entry: getBrainPrompt(currentDate: string): string (line 66) Schema of LLM output: BrainOutput type at line 39 — declares intent, onion_signals, entities, search_query, keyword_query, discovery_question, filters among others.

Purpose: tells Gemini how to extract the 8 signals + the next discovery question in one JSON response. Consolidated from an earlier 2-call design.

Carry-forward rule (prompt text): instructs the LLM to preserve existing signal values unless explicitly contradicted. F-026 lives here: this is prompt-only enforcement — no code-level safety net. If the LLM ignores the rule, nothing catches it. Step 3 fix = pushback_detector.ts pre-check.

2. Maverick System Prompt

File: lib/search/prompts/maverick.ts Entry: buildMaverickPromptWithPersona(dossierSummary, contextSources, discoveryInstructions, turnCount, isStrictDiscovery): Promise<string> (line 12)

Structure (sandwich):

[PERSONA IDENTITY]
  ← loaded from config/system/PERSONAS.md via persona_loader.ts
[OFFICIAL KNOWLEDGE]  
  ← the formatted source chunks from formatHitsForLLM(chunks)
[FINAL DIRECTIVES]
  ← discoveryInstructions + dossierSummary + turn-specific rules

Observed size: ~16KB baseline. F-006 BUG: non-monotonic spike to 157KB on turn 1 (root cause unknown).

F-032 suspect: a "NAMEDROP" instruction is loaded from config/system/PERSONAS.md line 33:

3. **NAMEDROP**: Aggressively cite customer quotes and examples using markdown links `[Customer](URL)`.

The LLM is echoing this instruction heading verbatim into UI ("Namedrop: Gymshark"). Step 3 fix: either (a) strip the word "NAMEDROP" from the prompt (rename the behavior), or (b) add an auditor scrubber that removes any ^Namedrop: lines from the response.

F-034 suspect: the dossier block (which contains the newest user-provided signals) is dwarfed by the 16KB of static behavioral rules. Step 4c = trim static prompt, elevate dossier.

3. PERSONAS.md (external config file)

File: config/system/PERSONAS.md Loaded by: persona_loader.loadPersonaDefinition(persona) → cached in memory Contains: tone of voice, behaviors, forbidden phrases for all three personas (maverick, elena, bruno)

Note on the elena/bruno entries here: these are REFERENCE docs for the humans, not the actual prompts the specialists run on. Elena and Bruno's live prompts are in Agent Studio. The PERSONAS.md entries for elena/bruno may describe intended behavior, but the source of truth is Agent Studio.

For Maverick: PERSONAS.md IS load-bearing — its maverick block becomes part of the runtime system prompt via formatPersonaForPrompt().

Agent Studio Prompts (remote, NOT in git)

Elena (Solutions Engineer)

  • Agent ID: f029acbb-a7a0-43b1-9a85-a14ef3907cd3
  • Location: Agent Studio dashboard
  • What it knows: Algolia SaaS feature set, merchandising, analytics, dashboard, personalization
  • Message protocol: receives <user_question>...</user_question> + <extracted_entities>...</extracted_entities> blocks from our backend via buildAgentStudioMessage()
  • Triggers:
  • handshake — canned "EXECUTE HANDSHAKE PROTOCOL" instruction tells it to summarize-back and ask a clarifier (no technical answers yet)
  • execute / consent — full deep dive on the expandedQuestion carried from Maverick

Bruno (Principal Architect)

  • Agent ID: facb549e-8f27-47e9-9e42-e20032b0f1a1
  • Location: Agent Studio dashboard
  • What it knows: Algolia infrastructure, scale, integration, SDK, API patterns, architecture diagrams
  • Protocol: same as Elena

⚠️ Asymmetry risk: Specialist prompts can change out-of-band (via Agent Studio UI) without triggering any CI/test. We should version-tag the Agent Studio agents and log the version on each call. [TODO — Step 6 scope?]

Legacy Prompts (likely DEAD — verify)

These exist in lib/search/prompts/ but do not appear on the ALIVE path traced in Runs 001–006. [UNVERIFIED — run grep for callers before removing.]

  • prompts/fallback.ts — FALLBACK_SYSTEM_PROMPT, FALLBACK_FOLLOWUPS
  • prompts/casual.ts — CASUAL_PROMPT, CASUAL_SYSTEM_PROMPT
  • prompts/consultant.ts — getSEPrompt(isComplex, fullContext, mode)
  • prompts/squad.ts — SQUAD_PROMPT
  • prompts/support.ts — SUPPORT_PROMPT
  • prompts/se.ts — SE_XML_SCHEMA, getSEPrompt(context)

Action item for a later audit step: grep each file for import sites; if none are in the ALIVE call graph, delete.

Prompt-Level Known Issues (F-numbers)

F# Prompt Issue Fix
F-006 Maverick 16KB → 157KB spike on some turns Step 4c — root-cause
F-032 PERSONAS.md line 33 "NAMEDROP:" heading echoed verbatim Step 3 — rename + auditor scrubber
F-034 Maverick sandwich Static rules drown live dossier Step 4c — trim static, elevate dossier
F-036 Maverick No anti-repetition guidance Step 4 — prompt addition + session state
F-039 Maverick + specialists No recency preference for sources Step 4 — add "prefer sources within 18 months"
F-037 Elena (Agent Studio) Handshake summary is a paragraph, not bullets Agent Studio UI edit

Cross-references

  • 03-Files-Reference — prompts/ directory catalog
  • 04-Functions-Reference — buildMaverickPromptWithPersona, getBrainPrompt
  • 07-Personas-Reference — how personas tie to prompts
  • 10-Known-Issues — F-006, F-032, F-034, F-036, F-039