AI Scribe Configuration Guide

For Healthie customers configuring AI Scribe for their organization. It covers form design, field configuration, Custom Instructions, and how to get the most consistent output from your charting setup.

How AI Scribe Works

AI Scribe listens to your session transcript and fills your charting form based on what was discussed. The quality of its output depends almost entirely on how your forms are built and configured.

There are three surfaces that shape Scribe's behavior:

• Field labels: The primary signal Scribe uses to understand what content belongs in each field
• Placeholder text: Controls structure and formatting within a field
• Custom Instructions: Org, appointment type, or form-level rules for tone, clinical logic, and documentation behavior

All three surfaces are treated as instructions by the AI. Using each one for its intended purpose leads to more consistent output and makes issues easier to diagnose when something isn't working.

Field Labels

Field labels are the most important thing you can configure. Scribe reads your label to decide what content belongs in each field — a vague label produces vague output.

Good label principles:

• Be specific and descriptive: tell Scribe exactly what content belongs here
• Include clinical context when relevant (e.g. "today's session" vs. "all history")
• If a field is consistently mis-filled, fix the label first before adding a Custom Instruction

For more detail and field-specific examples, see Writing Effective Form Labels for AI-Generated Charting Notes.

Placeholder Text

Placeholder text is the most reliable way to control the structure and format of a field's output. The AI treats your placeholder as a formatting template to follow when filling the field.

Use placeholder text when a field needs:

• A specific layout or multi-part structure
• Bullet or list formatting
• Sub-labels or section breaks within a single field

Important: Bullet point formatting cannot be controlled via Custom Instructions. If you want Scribe to produce bulleted output, configure it in the field's placeholder — not in instructions.

Excluding Fields from Scribe

Any field in the Form Builder can be excluded from Scribe using the "Exclude Field from Scribe" checkbox.

Use this for:

• Administrative or billing fields that should never be auto-filled
• Consent or legal fields you want to keep fully manual
• Fields where Scribe consistently produces incorrect output
• Fields that are always pre-filled or carried over from the previous note

💡 This is more reliable than writing "do not fill this field" in Custom Instructions. When a field is excluded, it is hidden from the AI entirely — not just instructed to skip it.

Custom Form Instructions

Custom Instructions are plain-language directives that tell Scribe how to document specific information. They can be set at three levels — organization, appointment type, and form — and are injected into the Scribe prompt at runtime.

Instruction levels:

• Organization-level: Apply to all Scribe-generated notes across your org
• Appointment type-level: Apply to notes generated for a specific appointment type
• Form-level: Apply every time Scribe generates a note from a specific charting form

Instructions at lower levels (form) take precedence over higher levels (org) when there's a conflict.

When to use Custom Instructions

Custom Instructions are for behavior and rules that can't live in a label or placeholder:

• Tone or clinical voice (e.g. third-person, formal medical language)
• Cross-field logic (e.g. comparing a value against a previously documented one)
• Specialty-specific documentation requirements
• Fallback behavior for fields where content wasn't discussed

Keep them minimal. Every instruction added is a potential conflict point. Start with the label and placeholder — only reach for Custom Instructions when those aren't enough.

How to write effective instructions

Do:

• Target a specific field by name: For the [Field Name] field: ...
• State what to do affirmatively, not just what to avoid
• Use plain, direct language
• One instruction per field — keep it focused

Don't:

• Write vague directives like "be more detailed" without specifying a field
• Add instructions for fields Scribe already handles natively (Medications, Allergies, Diagnosis, Date of Birth, Name)
• Write conflicting instructions across levels without accounting for precedence

Note: Custom Instructions cannot reliably enforce sentence counts or length limits. For fields where brevity matters, set that expectation in the field label (e.g., Subjective — summarize in 3–5 sentences ) or model the structure in placeholder text.

Instruction examples

Exact structure:

For HPI - SI/HI: document current status, any attempts in the past 6 months, and any thoughts with intent or plan in the past 6 months

Hard constraint:

Interventions: ≤10 words per line

Direct quote:

For Chief Complaint: document a direct patient quote, 1–2 sentences maximum

Exact format:

Dietary Recall: use this exact format: Meal (time if reported) - foods, beverages, context

Fallback for missing content:

If scheduling was not discussed, write: Not discussed

Sensitivity rule:

For Trauma History: provide a high-level summary only — do not include specific acts, locations, or perpetrator information

Status comparison:

Compare against the previously documented value and use one of these labels in all caps: IMPROVED, WORSE, NO CHANGE

Clinical terminology:

Use ICD-10 language for the primary diagnosis. For working diagnoses, write 'likely' or 'probable' rather than definitive terms.

Medication documentation:

For the Plan - Medications field: list new prescriptions with dose, route, frequency, quantity, and refills. Only document continued medications if a change was discussed.

Clinical voice:

Use formal medical language throughout. Refer to the individual as 'patient' — not 'client' or 'member'.

Avoid phrases like 'the patient is doing well' — use 'patient reports improvement in symptoms' or equivalent language grounded in what was reported.

The "Not reported" rule — always scope it

If you want Scribe to write "Not reported" for fields where content wasn't discussed, use this exact phrasing:

"If a data point was not discussed and has no previously documented value, write: Not reported."

⚠️ Without the scoping clause ("and has no previously documented value"), this rule will override pre-fill and wipe out values carried forward from previous notes. This is one of the most common causes of unexpected blank fields after adding Custom Instructions.

Safe baseline for forms with pre-fill or copied fields

If your form uses pre-fill or copy fields, these two rules together are a safe minimal starting point:

1. Never invent, estimate, or infer values. Only document what the patient explicitly reported during this session.
2. If a field or data point was not discussed and has no previously documented value, write: "Not reported."

⚠️ These two rules must always be used together. Rule 1 alone could cause Scribe to ignore values carried forward from previous sessions. Rule 2's scoping clause is what protects pre-fill. Neither rule is safe without the other on a form that uses pre-fill or copy fields.

Troubleshooting

Testing tips:

• Test carry-forward behavior using practice sessions that deliberately skip certain fields before applying new instructions to a live account
• Debug one change at a time — don't add multiple new rules in a single update