Files
audita/docs/internal/prompts.md

6.9 KiB

Audita Prompt Registry

internal/prompts embeds eleven PromptKit definitions in the audita collection. The four proposal IDs are audita/modules.glossary.proposal, audita/modules.homophones.proposal, audita/modules.spoken_word.proposal, and audita/modules.grammar.proposal; the corresponding repair IDs replace .proposal with .repair. The three validator IDs are audita/validators.spoken_form_plausibility, audita/validators.meaning_reversal_review, and audita/validators.editorial_review.

PromptKit composes embedded defaults with operator prompt sources. Shared instructions come from the embedded fragments in assets/shared; the request shared-variable helper fills absent HardeningPolicy, ProposalContract, RepairContract, and ValidationContract variables. The processing adapter supplies the embedded instruction fragments for those names. Processing supplies Audita's response-schema contract separately. The operator's prompt definition controls which variables its template uses.

Proposal focus and validator acceptance intentionally differ: minor editorial cleanup may be accepted even when the proposing module was not asked to perform it. Follow the architecture boundary when maintaining proposal, validation, and repair instructions; the difference alone is not a reason to tighten validation. The testing rationale is recorded in ADR 0003.

Bundled proposal system messages carry durable correction principles and the editorial allowance during repair. The initial user message carries each module's focused proposal assignment and exclusions. Repair can therefore give a subsequent reassessment assignment without inheriting a system prohibition on acceptable incidental cleanup. Review complete conversations when editing these roles, including the transition from a correction set to one repair result.

For a standard request preview or validation, select a native PromptKit profile and supply the template variables used by the selected prompt. The shipped proposal definitions use TranscriptDescriptionBlock, GlossaryJSON, ProtectedTermsJSON, and SectionJSON. Glossary entries provide context, and the separate spelling list defines protection. Preview defaults the spelling list to [] when omitted. The validator definitions use TranscriptDescriptionBlock and PayloadJSON. The latter is supplied candidate JSON and does not require a proposal inference call. Repair definitions use RepairContract and RepairRequestJSON, containing the original proposal reference, current correction, and ordered findings. When the target exists, the request also includes original_segment_text; when the correction is applicable, it includes corrected_segment_text. These fields describe a preview of the current version, not an applied change. An inapplicable correction omits the resulting text and retains its findings and available source text. An operator replacement may use different variables. See the upstream CLI reference for the standard preview, validation, and smoke commands.

The correction-set schema requires a string replacement and accepts an empty string. Proposal guidance uses it for eligible span deletion and permits literal spacing edits; validator guidance evaluates the full before/after segment under each validator's existing remit. A blank resulting segment remains a domain rejection, not a structural schema error.

internal/framework/responseschema remains the only embedded source for correction_set.v1.json, correction_repair.v1.json, and validator_decision_set.v1.json. It exposes that filesystem to PromptKit and retains Audita's schema-key lookup. PromptKit's prepared execution supplies definition and rendered hashes; Audita does not recompute or promise equality with hashes from the removed template renderer. The small Audita registry records only prompt ID, source, and embedded path. Prepared runtime metadata belongs in diagnostics rather than the registry.

The structured-call contract carries prompt ID, string variables, response-schema key, and logical-call attribution. Module and validator callers pass these values through the role-bound adapter. See the LLM runtime for runtime assembly and configuration for operator-selected profiles.

Proposal instructions describe literal matching, each module's replacement policy, and source-based proposal identity. They request independently useful edits and a combined proposal when edits overlap or depend on one another, while allowing independent edits to share a segment. This is generation guidance; application still uses the existing ordering and applicability checks. Proposal id and validator correction_index values are short, one-based references scoped to each request, not internal transcript/proposal identities. Mapping belongs to proposal generation and validator reconciliation. Validator decisions use approved for the verdict. Approval examples use an empty reason; rejection guidance requests a specific defect and supplied evidence within the validator's remit. The model explains defects; repair owns revision or withdrawal. This is prompt guidance, not a runtime nonempty-reason check. Compact output examples illustrate the supplied schema without requiring fixed JSON formatting or key order. The grammar article exception and glossary mishearing exception apply consistently across their instructions.

Only the three active validator definitions are retained. The unused internal grammar_review and spoken_word_review definitions and type selections were removed; built-in chains and operator configuration are unchanged.

Repair guidance reassesses the proposal against the original transcript, context, and findings. Unsupported, unnecessary, or unresolved uncertain corrections may be withdrawn, preserving the original text. Otherwise acceptable minor editorial cleanup remains permissible during repair.

Examples contrast meaningful apparent filler with removable hesitation and show both revision and withdrawal. Treat their words as contextual illustrations, not unconditional triggers for deletion or replacement.

The meaning-reversal validator has a deliberately narrow remit: reversal of the full segment's assertion, not every change of meaning. Its prompt distinguishes changes of referent from reversal and asks rejection reasons to identify the opposing assertions. Preserve its carefully tuned core instructions when editing; other validators assess other criteria.

Prompt tests protect rendering with supplied data, resource selection, schemas, and integration behavior. They do not freeze bundled prose with word/phrase checks or snapshots. Review editorial intent directly; offline tests cannot establish live-model editorial quality.