​
ADR-0025: DB-managed LLM prompts as canonical, no code fallback

​
Status

Accepted

​
Tags

ai, prompts, llm, fieldforce, briefing

​
Decision

For LLM features that use the ai_prompt_templates table, the database is the sole source of truth for the active prompt. There is no code-shipped LLM prompt fallback.
  • Code-shipped seed files under backend/go/internal/modules/ai/seed_prompts/<feature_key>/<locale>.tmpl exist only to seed v1 rows during the initial migration. They are not consulted at runtime.
  • If the DB read fails for any reason (empty active row, missing table, connection error, malformed template), the pipeline MUST log loudly, record an AccessGate error, skip the LLM call, and fall back to the heuristic-only generation path for that tick.
  • “Heuristic-only” is the same well-tested branch that fires when AccessGate denies an LLM call (trial exhausted, plan cap, kill-switch). It is not LLM-related; it produces a deterministic templated summary from already-computed metrics.
This applies to every feature backed by ai_prompt_templates. The first consumer is Phase 4 fieldforce briefings.

​
Why

The instinctive design is to ship a code constant as an “emergency fallback” — if the DB is unreachable, the system can still call the LLM with the constant. This is wrong for two compounding reasons:
  1. A stale constant is more dangerous than no LLM call. Once a prompt has been tuned through 3-4 DB versions, the code constant is the original v1 from months ago. When the emergency fallback fires, the LLM produces output the org has never seen — at exactly the moment something else is already broken. Users perceive this as “the AI got worse” rather than “the database is down.”
  2. The fallback path is not the rare path. A code constant only catches catastrophic DB failure (table missing, connection lost). The far more common failure modes — empty active row after a botched activation, malformed template after an edit, transient query timeout — all need to be handled anyway, and they should all converge on the same well-tested branch. Having two failure paths (code-fallback for catastrophic, heuristic for ordinary) doubles the test surface and the failure-mode reasoning.
The heuristic-only path is already exercised every time AccessGate denies a call (trial users, paused plans, kill-switch tests). It is the most-tested failure branch in the system. Routing every DB-prompt failure through that same branch means the failure behavior is predictable, locale-correct, and visually consistent with what users see on plan denial — they get a deterministic summary instead of mystery output. Code-shipped seeds remain useful for one moment only: bootstrapping v1 during the migration. After that, the DB is canonical. Rejected alternatives:
  • Code constants as emergency LLM fallback. The original design. Rejected for the reasons above.
  • DB row as canonical + code constant as identical mirror, kept in sync by PR review. Requires a manual copy-back step after every prompt tuning. Skipped under time pressure → drift → stale fallback. Rejected.
  • No seeding at all (admin must create v1 manually). Adds a deploy-blocking manual step. Rejected — bootstrap convenience is real.

​
How it works

Read path (every LLM call): 
template, err := promptRepo.GetActive(ctx, "fieldforce:briefing", orgLocale)
if err != nil || template == "" {
    log.Error("prompt template unavailable", "feature", "fieldforce:briefing", "locale", orgLocale, "err", err)
    accessGate.RecordError(ctx, "fieldforce:briefing", err)
    return generateHeuristicOnly(ctx, inputs) // same path as gate-denied
}

rendered := renderTemplate(template, inputs)
result, err := llm.Call(ctx, rendered)
if err != nil {
    // ... existing LLM-failure handling, also falls back to heuristic-only
}
Migration seeding (runs once, at table creation): 
func CreateAIPromptTemplates(db *gorm.DB) error {
    // create table, indexes, partial unique index ...
    for _, locale := range []string{"en", "zh", "ms"} {
        body, err := os.ReadFile(fmt.Sprintf("seed_prompts/fieldforce_briefing/%s.tmpl", locale))
        if err != nil { return err }
        db.Exec(`INSERT INTO ai_prompt_templates (feature_key, locale, version, template, is_active, created_by)
                 VALUES ('fieldforce:briefing', ?, 1, ?, true, 'system:migration')`,
                 locale, string(body))
    }
    return nil
}
Post-migration, the seed files are inert. They are still checked into git for reviewability and disaster-recovery (rebuilding a fresh environment), but no runtime code path reads them.

​
Known limitations

  • A catastrophic DB-prompts outage means all LLM calls for that feature fall to heuristic-only across the platform. This is the intended behavior, but it means observability matters: fieldforce_briefings_total{mode="heuristic_only"} should be alarmed if it crosses a threshold relative to flag-enabled orgs.
  • Recovering a corrupted active row requires a platform-admin action (re-activate a prior version), not an automatic code rollback. This is intentional — automatic rollback to code would defeat the whole “DB is canonical” guarantee.
  • Disaster recovery from a complete data loss requires re-running the migration’s seed step. Seed files MUST stay current enough that a v1 restore is acceptable as a temporary state until the platform admin restores known-good versions from backup.

​
Rules for agents

  • Features backed by ai_prompt_templates MUST NOT define an in-code LLM prompt constant as a runtime fallback.
  • Features MAY ship seed_prompts/<feature_key>/<locale>.tmpl files for migration bootstrap. They MUST NOT be referenced from any runtime code path.
  • DB prompt read failures MUST fall through to the existing heuristic-only / gate-denied path, never to a code constant.
  • Heuristic-only templates (deterministic locale-specific text built from metrics) ARE allowed in code — they are not LLM prompts.

​
Bad pattern (do not generate)

// In-code LLM prompt constant as fallback:
const briefingPromptFallback = `You are a helpful assistant. Summarize: {{.Metrics}}...`

template, err := promptRepo.GetActive(ctx, "fieldforce:briefing", locale)
if err != nil {
    template = briefingPromptFallback // wrong: stale, untested, diverges silently
}
result := llm.Call(ctx, render(template, inputs))

​
Good pattern

template, err := promptRepo.GetActive(ctx, "fieldforce:briefing", locale)
if err != nil || template == "" {
    log.Error(...); accessGate.RecordError(...)
    return generateHeuristicOnly(ctx, inputs) // deterministic, well-tested
}
result := llm.Call(ctx, render(template, inputs))