Prompt Artifact Annotation Spec

Prompt Artifact Annotation Spec

This appendix is the book-facing copy of the maintained prompt artifact spec. It belongs near the tail of the book because most readers should first learn the practical prompt patterns, then use this section when they maintain reusable prompt artifacts.

prompt_id: support_triage version: 1 status: draft owner: support-ai models:

• gpt-4.1 compiled_output: prompts/support_triage.compiled.json evals:
• support_triage_core

---

Prompt: Support Triage

Block: Developer Instructions

role: developer
source_kind: static_instruction
send_to_model: true
authority: high
trust_boundary: instructional
annotations:
  - CRITICAL

Classify the user request into exactly one allowed support category.

Do not invent policy details.

[ASSERT: category_is_allowed] [ASSERT: no_policy_fabrication]

Block: Runtime User Message

role: user
source_kind: runtime_variable
send_to_model: true
authority: low
trust_boundary: user_supplied
annotations:
  - VAR
  - UNTRUSTED

{{user_message}}

Block: Maintainer Note

:::note maintainer send_to_model: false

The user message is marked as untrusted because it may contain prompt injection. :::

Assertions

assertions:
  category_is_allowed:
    type: enum_match
    applies_to: assistant_output.category
    allowed_values_ref: allowed_categories

  no_policy_fabrication:
    type: semantic_check
    applies_to: assistant_output.rationale
    runner: manual_or_llm_judge

## Compiler Requirements

A compiler for this format must:

- Emit only blocks with `send_to_model: true`.
- Preserve declared chat roles.
- Strip maintainer notes.
- Strip eval metadata.
- Strip visual-only annotations.
- Resolve runtime variables or leave explicit placeholders.
- Fail on unknown roles.
- Warn on assertions without registry entries.
- Warn when `user_supplied` content appears in a high-authority role.

## Renderer Requirements

A renderer should:

- Show role badges.
- Show source kind.
- Show trust boundary.
- Render annotation tokens visibly.
- Use color only as an enhancement.
- Clearly mark content that is not sent to the model.
- Keep examples visually separate from live prompt instructions.

## Invalid States

An artifact is invalid if:

- A `maintainer_note` has `send_to_model: true`.
- `runtime` is used as a role.
- `user_supplied` content has `authority: high` without an explicit transform.
- Assertions are shown as enforced but have no registry or runner.
- Rendered documentation cannot distinguish prompt text from notes.
- Compiled output includes annotation-only metadata.