Skip to main content

🧾 Prompt Assembly Engine & Templates Guide

This document explains how RABS stores, versions, and assembles prompt templates for every Large-Language-Model call that passes through the Central LLM Gateway.

1. The Three-Tier Prompt Stack​

To guarantee safety and consistency every prompt is built from three immutable tiers.
A lower tier can never override content injected by a higher tier.

┌──────────────────────────┐  Tier 1 – System  (immutable)
│ Prime Directives,        │  • Safety rules  
│ Documentation style, …   │
└────────────▲─────────────┘  (merged first)
             │
┌────────────┴────────────┐  Tier 2 – Situation  (specific)
│ Task-specific template   │  • Provided by calling module  
└────────────▲────────────┘
             │
┌────────────┴────────────┐  Tier 3 – Welfare   (optional)
│ Tone / UX instructions  │  • Plain language, empathy, etc.
└─────────────────────────┘
           ▼
 Final composite prompt sent to the model

Placeholders are substituted after the three tiers are concatenated.

2. Directory Layout & Naming​

All templates live in backend/llm/prompts/.

prompts/
 ├─ system/
 │   └─ prime_directives.v1.md
 ├─ situation/
 │   ├─ roster_auto_rebalance.v1.md
 │   └─ transport_route_plan.v2.md
 └─ welfare/
     ├─ plain_language.v1.md
     └─ empathetic_response.v1.md

Filenames follow the pattern:

<task_name>.v<MAJOR>.<MINOR>.md

Only MAJOR version bumps may introduce breaking placeholder changes.

Task keys consumed by the Gateway follow:

<domain>.<verb>.<version>      # e.g. transport.route_plan.v2

3. Template Anatomy​

Each template is a Markdown file that starts with a YAML front-matter block.

---
id: roster_auto_rebalance
version: 1.0
description: Adjust staff allocations when ratios fall below policy.
required_placeholders:
  - STAFF_SHORTFALL
  - CURRENT_ROSTER_JSON
---

You are Reggie, an adaptive scheduling agent.

The current roster JSON is:

{{CURRENT_ROSTER_JSON}}

Identify the best swaps to solve a staff shortfall of {{STAFF_SHORTFALL}}
while minimising overtime.  
Respond with a JSON array called `swaps`.

Rules:

  • Placeholders use {{PLACEHOLDER_NAME}} syntax.
  • All required_placeholders must be supplied by the caller or the Gateway returns HTTP 400.
  • Additional helper variables automatically injected by the Gateway:
    • {{SYS}} – current system date/time (ISO-8601)
    • {{MEM}} – memory snippets selected via vector search

4. Prompt Assembly Engine Workflow​

  1. Lookup – Module calls POST /llm/invoke with a task key and payload.
  2. Load templates – Gateway reads the System tier (always), Situation tier (task key), optional Welfare tier(s) requested via style_tokens.
  3. Substitute placeholders – Gateway injects caller-provided values plus {{SYS}}, {{MEM}}.
  4. Append safety footer – “If you are uncertain, respond with NEED_CLARIFICATION.”
  5. PII redaction & Prime-Directive enforcement – Final check before vendor call.
  6. Emit LLM_CALL event – Tokens, cost, latency logged to internalmonologue.

5. Style-Tokens & Helper Variables​

Content imported from docs_archive/prompts.md.

TokenEffect on Output
{{PLAIN}}Force grade-8 reading level, avoid jargon.
{{EMPATHETIC}}Use supportive, person-first language.
{{JSON_ONLY}}Respond with pure JSON, no prose.
{{NO_REFLECT}}Suppress chain-of-thought in final answer.

Modules request tokens by setting style_tokens: ["PLAIN","JSON_ONLY"] in their invoke payload.
The Welfare tier injects the corresponding template snippets.

6. Governance & Versioning​

  • Pull Request workflow for any change.
  • CI job lint-prompts.mjs validates YAML, placeholder coverage, and checks for banned terms.
  • Changes to system or welfare templates require approval by both Tech Lead and Clinical Lead.
  • Merge triggers Git tag prompts-vX.Y.Z and hot-reload in the Gateway.

🔗 Related Docs​

  • 01_Central_LLM_Gateway.md
  • ../01_Core_Concepts/01_Prime_Directives.md
  • ../02_Reasoning_&_Memory/05_Mind_Map_Data_Relationship_Index.md