Give the agent examples with a testable contract
Use when
A requested capability already exists in your own or reviewed example code. Instead of asking the agent to rediscover an API, point it to the smallest relevant implementation. Willison’s concrete case combines PDF-to-image rendering with image OCR.
Action
In the project’s existing examples location, keep source and fixture alongside the source revision, dependency versions, run command, expected output, and last successful run. Read actual code, not a webpage summary. Review permissions and dependencies, then recheck the relevant behavior in an already-authorized disposable environment. Supply only the needed examples, using this adaptable prompt:
“Read examples/A and examples/B. Verify their fixtures before reuse. Combine A’s input conversion with B’s processing; preserve their contracts and report incompatible APIs. Verify the integrated output against the specified fixture. Do not install dependencies or expand permissions without authorization.”
Acceptance check
Both examples must pass independently in the target environment; the combined application must then pass its own unchanged outcome check. For the OCR case, verify known image text and a three-page PDF: three ordered images, three expected page texts, and correct combined text. A deliberately broken PDF binding must fail even when image OCR passes. Keep revision, command, and result receipts; remove “known-working” status from failed or untested paths.
Evidence
Willison publishes the original composition prompt, source, and Playwright assertions. The counterexample is inspectable too: August’s merged PR 310 reports PDF rendering breaking while image OCR still worked. Its pinned repair explicitly imports the PDF.js namespace and awaits module readiness, rather than relying on a CDN bundle’s incidental global.
Caveat
No tests were run today, and no productivity gain was measured. Retrieved main-branch pages still show older imports, while the pinned merged revision shows the repair; live deployment status is unresolved. These fixtures do not prove general OCR accuracy or code safety. The revalidation procedure is our adaptation, not a new skill or automatic installation workflow.