The four kinds of context, and which one you left out

Here is a prompt that will disappoint you:

add tests for the parser

And here is the thing worth noticing: it is not disappointing because it is short. run the tests and fix what fails is shorter and works fine. It is disappointing because of what it leaves the agent to guess — which parser, which behaviour, what your tests normally look like, and how you will know it worked.

The documentation puts the constraint plainly: Claude can infer intent, but it cannot read your mind (Best practices). So the useful skill is not "write better prompts" in the abstract. It is being able to look at a bad result and name the specific thing you did not say.

Four kinds, and the failure each one prevents

The docs group effective prompting into four strategies. Read them as four separate kinds of context, because a prompt is rarely missing all four — it is usually missing exactly one, and which one predicts how it will go wrong.

Each of the next three lessons takes one of these apart. This one is about the diagnosis step, which is the part that transfers: once you can name which kind is missing, the rewrite is nearly mechanical.

Which one is yours missing?

Work backwards from the symptom. This mapping is this course's framing rather than something the docs assert, but every row of it is a failure the corresponding strategy is documented as preventing.

The second row is worth dwelling on, because it looks like a model problem and is not. It is the infinite exploration from Lesson 1.4, and both documented fixes — scope it, or hand it to a subagent — are things you supply, not things the model does better on the second try.

The rewrite is not "longer"

Take the opening prompt through all four.

add tests for the parser

Scope it — which unit, which case, and a constraint on how:

write tests for parseFrontmatter in src/lib/content/loader.ts, covering the
case where the YAML block is missing entirely. no mocks.

Point at a source, so the shape of the answer comes from the repo rather than from a guess:

...loader.test.ts already covers the happy path — read it first.

Point at the pattern, which is what makes the diff reviewable:

...match the table-driven style it uses. same describe/it nesting.

Say what "done" looks like, so the loop can close without you:

...run pnpm test and iterate until it passes.

That last clause is the highest-leverage sentence in the whole prompt, and it is the subject of Level 5. A check the agent can run is the difference between a session you supervise and one you can walk away from.

The finished version is four sentences. Not a template, not a preamble about being a senior engineer — four facts the agent could not have known.

When vague is the right instrument

This is not a rule that specificity is always better, and the docs say so directly: a vague prompt is useful when you are exploring and can afford to course-correct. what would you improve in this file? will surface things you would not have known to ask about, which is exactly the point of asking it.

The distinction is whether you are trying to get a specific thing or trying to find out what the specific thing should be. Vagueness is a poor instruction and a good question. The failure is using it as an instruction and then being annoyed at the answer.