SOP AI-KB-01: AI Knowledge Base (v1.8)¶
Status: Production Ready
Last Updated: 2026-01-21
Owner: Protocol Raw Operations
Platform: Supabase PostgreSQL
Overview¶
Centralised knowledge base that stores all AI prompt content in versioned, structured sections. Both the email triage system (CS-01) and live chat system (CS-02) assemble their prompts from this single source of truth.
Key Achievement: Update content once, both channels inherit the change. Full version history enables rollback. No code deployment required for prompt updates.
v1.8 Changes:
- Updated feeding_calculations to specify all amounts are for Protocol Raw Complete specifically
- Added clarification that caloric density (1900 kcal/kg) is product-specific
- Added NEVER rule: "Give feeding amounts without specifying they're for Protocol Raw Complete"
- feeding_calculations now at version 3
Architecture¶
+------------------------------------------+
| ai_knowledge_sections |
| (versioned content - 16 sections) |
+------------------------------------------+
|
| assembled by
v
+------------------------------------------+
| ai_prompt_templates |
| (assembly order per channel) |
+------------------------------------------+
|
| via function
v
+------------------------------------------+
| fn_assemble_prompt(channel) |
| -> Returns complete prompt string |
+------------------------------------------+
|
+--------+--------+
v v
+--------------+ +--------------+
| Email | | Chat |
| (Make.com) | | (Edge Fn) |
| ~4,000 tok | | ~4,500 tok |
+--------------+ +--------------+
Database Schema¶
Table: ai_knowledge_sections¶
Stores the actual content, versioned.
| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| section_key | TEXT | Unique identifier (e.g., 'brand_identity') |
| version | INTEGER | Version number within section |
| title | TEXT | Display title (e.g., 'BRAND IDENTITY') |
| content | TEXT | The actual prompt content |
| is_active | BOOLEAN | Only one version per section_key can be active |
| created_at | TIMESTAMPTZ | When this version was created |
| created_by | TEXT | Who created it |
| notes | TEXT | Change notes |
Constraint: unique_section_version ensures no duplicate version numbers per section.
Table: ai_prompt_templates¶
Defines which sections are included in each channel and in what order.
| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| channel | TEXT | 'email' or 'chat' |
| section_key | TEXT | References section to include |
| section_order | INTEGER | Assembly order (10, 20, 30...) |
| is_included | BOOLEAN | Whether to include this section |
| wrapper_prefix | TEXT | Optional text before section |
| wrapper_suffix | TEXT | Optional text after section |
Table: ai_prompt_logs¶
Audit trail of assembled prompts (for debugging).
| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| channel | TEXT | Which channel assembled |
| assembled_at | TIMESTAMPTZ | When |
| section_versions | JSONB | Which version of each section was used |
| prompt_hash | TEXT | Hash of assembled prompt |
| token_estimate | INTEGER | Approximate token count |
Current Sections¶
| section_key | Title | Applies To | Purpose |
|---|---|---|---|
| brand_identity | BRAND IDENTITY | Both | Voice, tone, terminology (company vs product) |
| response_principles | GENERAL RESPONSE PRINCIPLES | Both | 11 principles (consolidated) |
| product_knowledge | PRODUCT KNOWLEDGE | Both | SKU, pricing, ingredients, nutritional analysis, value justification, environmental position, ingredient language guidance, FEDIAF verification guidance |
| safety_verification | SAFETY & VERIFICATION | Both | Batch testing, proof portal |
| storage_serving | STORAGE & SERVING | Both | Freezer, defrost, serve |
| feeding_calculations | FEEDING CALCULATIONS | Both | RER/MER, reference examples for Protocol Raw Complete, calculator link |
| transition_guidance | TRANSITION GUIDANCE | Both | 10-day schedule, week-by-week, warning signs, contraindications |
| delivery_logistics | DELIVERY & LOGISTICS | Both | DPD, dispatch days, packaging |
| self_service_portal | SELF-SERVICE PORTAL | Both | Portal features, 48-hour lock |
| common_scenarios | COMMON SCENARIOS | Both | Shared Q&A scenarios |
| escalation_rules | ESCALATION RULES | Both | AI judgment-based (rewritten) |
| hard_boundaries | HARD BOUNDARIES - NEVER DO | Both | Prohibitions |
| email_context | EMAIL CONTEXT | Email only | Role definition for email |
| email_format | EMAIL RESPONSE FORMAT | Email only | JSON output specification |
| chat_context | CHAT CONTEXT | Chat only | Role definition for chat |
| chat_format | CHAT RESPONSE FORMAT | Chat only | Short responses, markdown links |
Terminology (Current - v1.5)¶
The brand_identity section now includes explicit terminology rules at the top:
TERMINOLOGY (CRITICAL): - "Protocol Raw" = the company name - "Protocol Raw Complete" = the product name (what customers feed their dogs) - Never use "Protocol Raw" alone when referring to the food — always "Protocol Raw Complete" - Correct: "Protocol Raw tests every batch..." (company action) - Correct: "Protocol Raw Complete is suitable for all life stages..." (product attribute) - Correct: "Protocol Raw Complete meets FEDIAF requirements..." (product specification) - For deliveries, use natural language: "your order", "your box", "your delivery"
Feeding Calculations (Current - v1.8)¶
The feeding_calculations section provides reference examples specific to Protocol Raw Complete:
Reference Examples for Protocol Raw Complete (moderate activity, neutered, ideal body condition):
These amounts are specific to Protocol Raw Complete based on our caloric density of 1900 kcal/kg. Other raw foods have different caloric densities, so these figures won't apply to other brands.
- 10kg dog: ~275g of Protocol Raw Complete per day
- 15kg dog: ~375g of Protocol Raw Complete per day (anchor example)
- 25kg dog: ~550g of Protocol Raw Complete per day
- 35kg dog: ~700g of Protocol Raw Complete per day
Variation factors: - Activity level: Low needs ~10% less, high needs ~20% more - Neuter status: Intact dogs need ~20% more than neutered - Body condition: Overweight gets ~10% less, underweight gets ~10% more - Life stage: Puppies need 1.5-2x adult amounts depending on age
AI guidance: - CAN share reference examples to be helpful (e.g., "A 15kg moderately active neutered dog typically needs around 375g of Protocol Raw Complete per day") - MUST always recommend the calculator for their specific dog - NEVER do live arithmetic in responses - NEVER give feeding amounts without specifying they're for Protocol Raw Complete
Transition Guidance (Current - v1.4)¶
The transition_guidance section now includes:
The 10-Day Schedule: Replace portions of current food with Protocol Raw Complete - don't add on top. Total daily food stays roughly the same. - Days 1-2: 25% Protocol Raw Complete, 75% current food - Days 3-4: 50/50 - Days 5-6: 75% Protocol Raw Complete, 25% current food - Days 7-8: 90% Protocol Raw Complete, 10% current food - Days 9-10: 100% Protocol Raw Complete (use calculator amount)
New in v1.4: - "Hunger pukes" explanation (yellow bile vomit, usually morning) - solved by smaller meals or bedtime snack - Contraindications: Dogs with pancreatitis, severe kidney/liver disease, or immunocompromised dogs should consult their vet before starting raw
Response Principles (Current - v1.2)¶
The response_principles section contains 11 consolidated principles:
| # | Principle | Purpose |
|---|---|---|
| 1 | Answer first, explain second | Lead with direct answer |
| 2 | Pivot to proof on safety/comparison | Land the differentiator (batch testing, proof portal) |
| 3 | Match the customer's register | Adapt formality to customer |
| 4 | Don't volunteer negatives | Only address raised concerns |
| 5 | End clean | No unnecessary follow-ups |
| 6 | Stay in your lane | No vet advice, no debates |
| 7 | When you don't know, say so | Don't fabricate |
| 8 | Answer suitability confidently | Use data, defer only for diagnosed conditions |
| 9 | Justify value, don't apologise | Stack value on price questions |
| 10 | Novel situations | Apply voice, check boundaries |
| 11 | Use conversation context | Connect questions across session |
Key consolidation: Principles 11-15 from v1.1 (suitability, confidence calibration, differentiator, etc.) were merged into principles 2, 8, and 9.
Escalation Rules (Current - v1.2)¶
The escalation_rules section now uses AI judgment instead of keyword matching.
AI Should Escalate¶
- Product quality/safety issues with customer's order
- Refund or compensation requests
- Complaint escalation signals (legal, social media, aggressive)
- Bereavement
- B2B inquiries
- Genuine uncertainty
AI Should NOT Escalate¶
- General raw feeding safety questions ("My vet says raw is dangerous")
- Suitability questions ("Is this ok for my senior dog?")
- Comparison shopping ("Why choose you over Butternut?")
- Price questions ("Why so expensive?")
Why this matters: Keyword matching caused false positives. "My vet says raw is dangerous" contains "vet" but is a sales objection, not a crisis. AI judgment handles this correctly.
Product Knowledge (Current - v1.7)¶
The product_knowledge section now includes:
FEDIAF Compliance (updated v1.7): - FEDIAF All Life Stages compliant — and independently verified - An accredited laboratory has tested our formulation and confirmed it meets FEDIAF's strictest nutritional standard - Suitable for puppies, pregnant/nursing dogs, and all adults - We publish the full analysis
FEDIAF & Nutritional Completeness Guidance (new in v1.7):
When customers ask whether Protocol Raw Complete is "complete," "balanced," or meets nutritional standards — always land the verification differentiator. Don't just confirm compliance; explain that it's independently proven and published.
Angle 1 — Verified, not just formulated: "Yes, Protocol Raw Complete meets FEDIAF All Life Stages standards — the strictest level. But we don't just design to that standard. An independent laboratory has tested our formulation and confirmed it meets every requirement. We publish the full report."
Angle 2 — The proof is public: "We publish the complete nutritional analysis showing actual measured levels of protein, fat, calcium, phosphorus, vitamins, and trace minerals. You can see exactly how our food meets FEDIAF standards — not just take our word for it."
Angle 3 — Answering vet scepticism: "Many vets worry that raw diets aren't nutritionally complete. That's a fair concern for DIY or unverified brands. Protocol Raw Complete has independent lab verification confirming FEDIAF compliance — your vet can review the published analysis."
Angle 4 — Comparison to competitors: "Most brands say 'formulated to FEDIAF standards' — meaning they designed the recipe on paper. We send our food to an independent lab, they measure the actual nutrient levels, and we publish the results. That's the difference between a claim and proof."
Key phrases to use: - "Independently verified" (not just "compliant" or "formulated to") - "Lab-tested and published" - "You can see the full nutritional analysis" - "Proof, not promises"
Never say: - "Trust us, it's complete" (undermines our differentiator) - "Designed by nutritionists" (don't fabricate collaborations) - "As good as" any other brand (we're making a distinct claim)
Ingredients (updated v1.6): - Beef: Heart, lean beef, green tripe, liver, kidney, spleen - Chicken: Bone-in chicken, gizzards - Marine: Dehydrated blue mussel, dehydrated oyster, fish oil (salmon/sardine) - Functional: Whole egg, sunflower seed meal, nutritional yeast, flaxseed oil, kelp meal
Ingredient Language Guidance (new in v1.6): - Use "lean beef" (not "trim") - Use "organ meats" (not "offal") - Use "whole animal nutrition" (not "by-products") - Never frame as "cheap cuts", "scraps", or "waste" - Don't list "chicken skin" separately — natural fats are included in the chicken component - Lead with nutritional function where possible
Nutritional Analysis: - Crude Protein: ~14% - Crude Fat: ~12% - Moisture: ~65% - Caloric density: 1900 kcal/kg
Digestive Suitability: - ~95% protein digestibility (vs ~85% for kibble) - Gut immunity markers research (2024 study) - Transition guidance
Value Justification: - Why we cost more - The value equation - Talking points for price questions
Environmental Position (v1.3, terminology fixed v1.5):
Address only when asked - this is supporting evidence, not the hero.
- Over 90% of Protocol Raw Complete comes from organ meats, bone-in proteins, and cuts outside human demand
- Research (Harvey et al. 2025) found prime meat content is primary driver of raw food's environmental impact
- Protocol Raw Complete estimate: ~2-3 kgCOâ‚‚-eq per 1000 kcal vs ~6-8 for typical raw (60-70% reduction)
Functions¶
fn_assemble_prompt(channel)¶
Assembles complete prompt for a channel by concatenating active section content in order.
Parameters:
- channel: 'email' or 'chat'
Returns:
- prompt: Assembled prompt text
- section_versions: JSONB of which version of each section was used
- token_estimate: Approximate token count
Example:
fn_add_section_version(...)¶
Adds a new version of a section.
Parameters:
- p_section_key: Which section to update
- p_title: Section title
- p_content: New content
- p_created_by: Who is making the change (default: 'system')
- p_notes: Change notes (optional)
- p_activate: Whether to activate immediately (default: false)
Returns: New version number
Example:
SELECT raw_ops.fn_add_section_version(
'response_principles',
'GENERAL RESPONSE PRINCIPLES',
'...new content...',
'anton',
'Added principle 11 for context awareness',
true -- activate immediately
);
fn_activate_section_version(p_section_key, p_version)¶
Activates a specific version of a section (for rollback).
Example:
Common Operations¶
View Current Active Content¶
SELECT
section_key,
version,
title,
LEFT(content, 100) as preview,
created_at
FROM raw_ops.ai_knowledge_sections
WHERE is_active = true
ORDER BY section_key;
View All Versions of a Section¶
SELECT
version,
is_active,
created_at,
created_by,
notes
FROM raw_ops.ai_knowledge_sections
WHERE section_key = 'response_principles'
ORDER BY version DESC;
Update a Section (Two Options)¶
Option A: Activate immediately
SELECT raw_ops.fn_add_section_version(
'response_principles',
'GENERAL RESPONSE PRINCIPLES',
'...new content...',
'anton',
'Description of change',
true -- activate immediately
);
Option B: Create then activate separately
-- Create
SELECT raw_ops.fn_add_section_version(
'response_principles',
'GENERAL RESPONSE PRINCIPLES',
'...new content...',
'anton',
'Draft for review'
);
-- Review
SELECT content FROM raw_ops.ai_knowledge_sections
WHERE section_key = 'response_principles'
ORDER BY version DESC LIMIT 1;
-- Activate
UPDATE raw_ops.ai_knowledge_sections
SET is_active = false
WHERE section_key = 'response_principles' AND is_active = true;
UPDATE raw_ops.ai_knowledge_sections
SET is_active = true
WHERE section_key = 'response_principles'
AND version = (SELECT MAX(version) FROM raw_ops.ai_knowledge_sections WHERE section_key = 'response_principles');
Rollback to Previous Version¶
Content Update Workflow¶
When improving AI responses based on feedback:
1. Identify the Gap¶
Review negative ratings or test conversations to find patterns.
2. Determine the Fix Type¶
| If the issue is... | Fix approach |
|---|---|
| AI doesn't know a fact | Add to product_knowledge |
| AI gives wrong tone | Update brand_identity |
| AI handles a category poorly | Update response_principles |
| AI escalates incorrectly | Update escalation_rules |
| AI does something forbidden | Update hard_boundaries |
| AI uses wrong terminology | Update brand_identity (terminology section) |
| AI uses commodity language | Update product_knowledge (ingredient language guidance) |
| AI doesn't emphasise verification | Update product_knowledge (FEDIAF guidance section) |
| AI gives generic feeding amounts | Update feeding_calculations (product specificity) |
3. Prefer Principles Over Scenarios¶
Don't add a specific scenario for one question. Add a principle that handles the category.
4. Test Before and After¶
Document the failing question, make the change, verify it's fixed, check you haven't broken other things.
Integration Points¶
Email Triage (Make.com CS-01)¶
- Module 15: HTTP request to Supabase RPC
fn_assemble_prompt - Module 5: Uses
{{15.data[1].prompt}}as system message
Live Chat (Edge Function v20)¶
- getSystemPrompt(): Calls
fn_assemble_prompt('chat')via Supabase client - Fetched at runtime for each conversation
Troubleshooting¶
Prompt Not Updating¶
-
Check active version:
-
Common issue: New version created but not activated
-
Fix: Activate the new version
AI Ignoring a Principle¶
- Check if the principle is in the active version
- Consider if it's buried too deep (move important principles higher)
- Make the principle more explicit with examples
Token Count Too High¶
Target: ~4,500 tokens per channel. If higher:
- Check for duplicate content across sections
- Remove verbose scenarios that can be covered by principles
- Consider if all sections are needed
Version History¶
v1.8 (2026-01-21) - Feeding Calculations Product Specificity¶
- Updated
feeding_calculationsto specify all amounts are for Protocol Raw Complete specifically - Added clarification that caloric density (1900 kcal/kg) is product-specific and won't apply to other brands
- Added NEVER rule: "Give feeding amounts without specifying they're for Protocol Raw Complete"
- Updated example response to include product name
- Added troubleshooting entry: "AI gives generic feeding amounts"
feeding_calculationsnow at version 3
v1.7 (2026-01-21) - FEDIAF Verification Guidance¶
- Added "FEDIAF & Nutritional Completeness" guidance section to
product_knowledgewith 4 response angles - Updated top-level FEDIAF bullet to emphasise independent lab verification and published results
- Added key phrases to use ("independently verified", "lab-tested and published", "proof, not promises")
- Added "never say" guidance for completeness questions
- AI now always lands the verification differentiator when answering completeness questions
- Added troubleshooting entry: "AI doesn't emphasise verification"
product_knowledgenow at version 15
v1.6 (2026-01-21) - Customer-Friendly Ingredient Terminology¶
- Updated ingredient listing: "trim" → "lean beef" (premium positioning)
- Removed standalone "skin" from chicken listing (natural fats included implicitly)
- Updated language guidance: "Lean beef" (not "trim")
- Added "Ingredient Language Guidance" subsection to product_knowledge
product_knowledgenow at version 14
v1.5 (2026-01-21) - Terminology Clarification¶
- Added company vs product terminology to
brand_identity: Protocol Raw = company, Protocol Raw Complete = product - Fixed product reference in
product_knowledgeenvironmental section (Protocol Raw → Protocol Raw Complete) brand_identitynow at version 3product_knowledgenow at version 13
v1.4 (2026-01-21) - Feeding & Transition Enhancements¶
- Expanded
feeding_calculationswith reference examples (10kg/15kg/25kg/35kg) so AI can give credible ballpark estimates while directing to calculator - Expanded
transition_guidancewith exact 10-day schedule, "hunger pukes" explanation, and contraindications (pancreatitis, kidney/liver, immunocompromised) feeding_calculationsnow at version 2transition_guidancenow at version 2
v1.3 (2026-01-21) - Environmental Position & Terminology Updates¶
- Added Environmental Position to
product_knowledge(address only when asked) - Updated FEDIAF terminology: "Growth & Reproduction" -> "All Life Stages" (customer-facing clarity)
- Updated ingredients: bone-in chicken (was "chicken frames"), dehydrated blue mussel/oyster (was "meat")
product_knowledgenow at version 12
v1.2 (2026-01-12) - Consolidation & AI Judgment¶
- Response principles consolidated from 15 -> 11
- Merged suitability/confidence principles into principle 8
- Added principle 11: Use conversation context
- Escalation rules rewritten for AI judgment (removed keyword matching)
- Product knowledge expanded with value justification
- Added "principles over scenarios" guidance
v1.1 (2026-01-12) - Principles & Nutritional Data¶
- Response principles expanded to 15
- Product knowledge updated with nutritional analysis
- Added critical note about activating new versions
v1.0 (2026-01-12) - Initial Release¶
- 16 content sections migrated from hardcoded prompts
- Assembly function for email and chat channels
- Version control with activation/rollback
Related Documentation¶
- SOP CS-01 v2.1: AI Customer Service Triage (Email)
- SOP CS-02 v1.6: Live Chat System
- Ops Portal Documentation v3.7: Portal overview (Support Workstation)
Document Owner: Protocol Raw Technical Team
Last Reviewed: 2026-01-21
Next Review: 2026-04-21
Version: 1.8
Status: Production Ready