Topic 4 — Prompt engineering fundamentals

Goal: Learn to get reliably great results from AI by writing better prompts.

Lesson 4.1 — The same model, two different answers

On her first morning at Trellix Health, Bina Velasquez typed into Scribe: "Summarize this visit." Out came a tidy paragraph that was, technically, a summary — and useless. It buried the medication change under small talk and never mentioned the follow-up the doctor ordered. She tried again: "Summarize this visit for the patient's chart. List, in order: the chief complaint, any medication changes, and the follow-up plan. Skip pleasantries." Same model, same transcript. This time the note was clean enough to send.

Nothing about the AI changed between those two tries. Only the instruction did.

A prompt is the instruction you hand the AI — the words that tell it what you want. And the thing Bina learned in five minutes is the thing this whole topic turns on: the same model gives wildly different results depending on how you ask. Vague in, vague out. Precise in, useful out.

Prompt engineering is clear thinking, written down where a machine can follow it — not a coding trick.

That reframe is good news for a former teacher. The instinct that made Bina good in a classroom — saying exactly what she meant, in the order a learner needs it — is the same instinct the work rewards.

Lesson 4.2 — Treat it like a brilliant, literal intern

Here's the mental model that fixes most bad prompts. Picture the AI as a new intern who has read almost everything ever written, remembers all of it, and will do precisely what you say — but cannot read your mind and will never ask a clarifying question. Leave a gap, and it fills the gap with a guess.

So you close the gaps. Two moves do most of the work.

Be specific. State exactly what you want and in what form. "Write something about diabetes" makes the intern guess the audience, length, and tone. "Write a 90-word reminder, at a sixth-grade reading level, telling a patient with type 2 diabetes how to prep for a fasting blood test" leaves nothing to guess.

Give context. Tell it the audience, the situation, and the constraints. Pri, the engineer Bina sits next to, once complained that Scribe's patient messages sounded cold. The fix wasn't a better model. It was one line of context at the top of the prompt: "These messages go to anxious patients who just had an unexpected test result. Warm, plain, no jargon." The tone problem vanished.

Specificity says what to produce. Context says the world it's being produced for. Most weak prompts are missing one or both.

Lesson 4.3 — Give it a role and a shape

Bina needed Scribe to draft clinical notes that read like a clinician wrote them — the right level of detail, the right restraint. The single most effective change she made was the first line of the prompt:

"You are an experienced clinical scribe documenting a primary-care visit. You write concise, factual notes and never invent details that aren't in the transcript."

That's a role (or persona). Telling the model who to be pulls its answer toward the right vocabulary, the right judgment, the right caution. It's a small move with an outsized effect.

The second move is to specify the format — the literal shape of the output. Do you want a bulleted list or a paragraph? A table? Three sentences or three hundred words? A formal tone or a friendly one? If you care about the shape, say so, or you'll get whatever the model defaults to.

Marc, the product manager, wanted Scribe's drafts to land in a fixed structure every time so clinicians could scan them fast. So Bina's prompt ends with the shape spelled out:

Output exactly four sections, in this order: Chief complaint, Assessment, Plan, Patient instructions. Each section is 1–3 short bullets. If a section has no content, write "None noted."

Notice that last sentence. Naming what to do when there's nothing to say is the difference between a prompt that works on the easy transcript and one that survives the messy real one.

Lesson 4.4 — Show, don't just tell (few-shot)

Bina could describe the house style of a good clinical note for a paragraph and still not nail it. What finally worked was showing the model what "good" looks like.

She pasted in three real transcripts, each paired with the exact note she wanted out of it — a messy visit, a routine checkup, and a tricky one with two unrelated complaints. Then she let Scribe handle the live transcript in the same style. The drafts snapped into line almost immediately.

This is few-shot prompting: giving the model a handful of examples of the input-to-output pattern you want, so it learns the target by demonstration. (Zero examples is "zero-shot"; a few is "few-shot.") It's one of the highest-return techniques there is — on many tasks a few good examples sharply tighten consistency and accuracy, especially when the output format or style is hard to describe in words. (On simple tasks with a strong instruction-following model, the gain can be small; for Bina's house-style note, where "good" is easier to show than to spell out, it was the move that worked.) And the surprising part is the math of it: quality beats quantity. Three sharp, diverse examples beat ten mediocre ones. And the models learn whatever you show them, flaws included, so a sloppy example teaches sloppiness. Pick examples that cover the range of real cases, and make every one of them exactly right.

One practical detail for the tool Trellix uses: with Claude, examples are usually wrapped in XML-style tags so the model can tell a demonstration apart from the live task. It looks like this:

<example>
  <transcript>Patient here for a med refill, BP 128/82, no new complaints.</transcript>
  <note>Chief complaint: medication refill. Assessment: stable, BP 128/82. Plan: refill issued. Patient instructions: None noted.</note>
</example>

Claude was trained to recognize that kind of structure, which is why tagged examples read so cleanly to it. That's a model-family habit, not a universal law — and the next lesson picks up that thread.

Lesson 4.5 — Let it reason, then iterate and test

Some questions don't yield to a single confident guess. When Dr. Marchetti flagged that Scribe was occasionally pairing the wrong dosage with the wrong medication on multi-drug visits, Bina added one instruction: "Work through the medications one at a time, matching each drug to its dosage and frequency from the transcript, before writing the Plan section." The errors dropped.

That's chain-of-thought: asking the model to reason step by step instead of jumping straight to an answer. On hard, multi-step tasks it reliably improves accuracy. One caveat worth knowing — skip explicit chain-of-thought when you're using a dedicated reasoning model (Claude's Extended Thinking, OpenAI's o-series, Gemini's Thinking models). Those already reason internally, so telling them to "think step by step" is redundant at best.

And structure preferences differ by model family. Claude responds well to XML-tagged instructions; some other models prefer a concise, JSON-style schema. Real prompts at Trellix often blend several of these at once — a role, a couple of examples, a required format, and a reasoning step — stacked in a single input.

But the part nobody can skip is iteration. Bina has never written a winning prompt in one shot, and neither will you. The loop she runs:

1. Write a first prompt and read what comes back.
2. Diagnose what's off — too long? wrong tone? missed a requirement? factually shaky?
3. Refine — add a detail, drop in an example, or correct the specific miss.
4. Repeat until it holds.

When a prompt is going into the product — hitting thousands of real, varied visits — one good result proves nothing. Bina tests across many inputs: the clean transcript, the rambling one, the one where the patient mentions three problems and the doctor addresses one. A prompt that only works on the example you wrote it against will break the moment a real clinic uses it.

Two rules she never bends, both carried over from earlier topics. Verify important output — the model can hallucinate a confident, wrong dosage (Topic 3), and in a clinic that can reach a real patient. And never paste sensitive data — real patient names, records — into a tool unless you know it handles that data safely (Topic 7).

Worked example — Building Scribe's discharge-summary prompt

Marc asks Bina for a prompt that turns a visit transcript into a plain-language summary the patient can take home. Watch the techniques stack.

She starts simple: "Summarize this visit for the patient." The draft is a wall of clinical text — accurate, unreadable.

She adds a role and context: "You are a clinical scribe writing for a patient with no medical training, who is a little anxious. Use plain, warm language and a sixth-grade reading level." Better tone, but it still wanders and skips the medication change.

She specifies the format: four labeled sections — What we talked about, What we found, What to do next, When to come back — each two or three short sentences. Now it's scannable.

It's still missing the house voice, so she adds two few-shot examples wrapped in <example> tags: one routine visit, one with a scary-sounding result handled gently. The drafts start sounding like Trellix.

For visits with several medication changes, she bolts on a chain-of-thought step: "First list each medication change from the transcript, then write the summary." Mismatches stop.

Finally she tests it against twelve real transcripts Pri pulls — short, long, multi-complaint, near-empty. Two break: one invents a follow-up date that was never said. Bina adds a line — "Only include a follow-up date if the transcript states one; otherwise write 'Your clinic will call to schedule.'" — and re-tests. Then Dr. Marchetti reads ten drafts to verify before it ships. One prompt, six techniques, a dozen tests, two expert sign-offs. That's the job.