Files
audita/docs/internal/prompts.md

112 lines
6.9 KiB
Markdown

# 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](../policy/architecture.md#correction-and-concurrency-invariants)
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](../adr/0003-module-focus-and-editorial-acceptance.md).
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](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/cli.md)
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](llm-runtime.md) for runtime assembly and
[configuration](../config.md) 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](modules.md) and
[validator reconciliation](validators.md). 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.