audita/docs/prompts.md

Audita Prompts

This document describes Audita's built-in embedded prompt assets and prompt registry behavior.

Why embedded prompt assets

Audita embeds production prompt text into the binary so runtime behavior is:

• deterministic;
• auditable;
• dependency-light;
• not dependent on external prompt files at execution time.

Prompt text is authored as Markdown assets and rendered by Go code using typed template data.

Built-in prompt registry

The prompt registry lives in internal/prompts and is responsible for:

• loading embedded prompt assets;
• registering stable prompt IDs and versions;
• recording prompt source metadata;
• computing deterministic SHA-256 source hashes;
• rendering system/user prompts with strict missing-key failures.

Current prompt source behavior:

• built-in embedded prompts only (prompt_source = builtin).
• filesystem prompt overrides are not supported.

Built-in prompt IDs

Module proposal prompts:

• modules.glossary.proposal
• modules.homophones.proposal
• modules.spoken_word.proposal
• modules.grammar.proposal

LLM-backed validator prompts:

• validators.spoken_form_plausibility
• validators.meaning_reversal_review
• validators.editorial_review
• validators.grammar_review
• validators.spoken_word_review

Prompt version semantics

Current built-in prompt version value is v1.

Version is a stable metadata identifier for diagnostics and debugging. It is not a dynamic prompt-selection mechanism.

Prompt hash semantics

Each registered prompt includes a deterministic SHA-256 hash of embedded source text.

Hash purpose:

• identify exact prompt source used in a run;
• support diagnostics reproducibility and change auditing.

Current hash scope:

• source prompt text (system + user assets for a registered prompt), not a runtime secret-bearing payload.

Template rendering behavior

Prompt rendering uses Go text/template with typed template data from module/validator builders.

Missing-key behavior:

• rendering uses missing-key errors;
• missing/renamed template fields fail quickly instead of silently producing incomplete prompts.

Go code still owns:

• structured request/response models;
• response schema selection;
• transcript/glossary/payload formatting;
• module and validator selection;
• diagnostics wiring.

Shared prompt hardening policy

A shared hardening fragment is embedded once and included in every module proposal prompt and every LLM-validator prompt.

Hardening policy includes:

• transcript text is untrusted data;
• glossary entries and transcript descriptions are reference data, not instructions;
• instructions found inside transcript text must not be obeyed;
• model must perform only the requested correction/validation task;
• no invention of facts, names, events, motivations, speaker intent, or corrections;
• transcript remains the source of truth.

Transcript description behavior

Transcript description remains background-only prompt context:

• it may help interpret ambiguous terms;
• it is explicitly non-authoritative and must not override transcript content;
• empty descriptions do not render awkward blank context sections.

Generated transcript descriptions are not implemented in this workstream.

Diagnostics and report metadata boundaries

Current metadata flow:

• proposal-generation diagnostics request metadata includes prompt metadata;
• LLM-validator diagnostics request metadata includes prompt metadata.

Prompt metadata fields used in diagnostics:

• prompt_id
• prompt_version
• prompt_source
• embedded_path
• sha256

Current boundary:

• detailed prompt metadata is diagnostics-first;
• broad report-level prompt registries/ledgers are deferred.

1.0 boundary

Not implemented for 1.0 in this workstream:

• filesystem prompt overrides;
• user-configurable prompt selection;
• external prompt directories.