A specification defines a problem precisely, constrains possible solutions, and sets criteria for judging the result. For a model-driven component, its prompt serves as a specification: it must state the task, inputs, constraints, and required output rather than merely express a goal. Ambiguity leaves multiple behaviors equally valid, making results harder to review and test. section 1.6.1 section 1.3
Make the contract explicit:
- Define the task and what counts as a good result. Include testable acceptance criteria. section 1.6.1
- Identify inputs and their types, including limits and meanings that a downstream user might otherwise have to guess. section 11.3.2
- Specify constraints, output fields, and fallback behavior so ordinary and unmatched cases have defined results. section 1.6.1 section 11.3.2
- Review, version, and test the prompt against representative inputs as a maintained system artifact. section 1.3
Feature-proposal assessment
“What do you think about this feature?” leaves the analysis and answer format open. A usable specification requests technical feasibility, user effect, and implementation risk; requires a structured assessment, recommendation, and confidence level; limits the assessment to supplied information; and caps it at 400 words. section 1.6.1
Table 11.4 Bare draft vs. documented draft for a ticket triage prompt
| Field |
Bare draft |
Documented draft |
|---|---|---|
| Name |
|
|
| Description |
— |
“Classifies inbound support tickets into one of five categories and assigns a priority level. Used by the routing service before tickets reach the queue.” |
|
|
— |
String. Full ticket text including subject line. Max 2,000 characters. |
|
|
— |
Enumeration: “1–5” (1 = critical) or “low/medium/high.” Must match the routing system’s expected format. |
| Temperature |
— |
0.2 (deterministic classification preferred) |
| Correct output looks like |
— |
JSON with fields: category (string), priority (string), confidence (float 0–1) |
| Fallback behavior |
— |
If the ticket does not match any category, return category: “unclassified” with confidence: 0.0 |
Compare a bare ticket-triage prompt with its documented interface. The documented version defines input types, JSON output fields, and an “unclassified” fallback—details needed to write consistent test cases. section 11.3.2
When results vary, inspect the specification before blaming the model. Look for interpretations the prompt still permits: an absent output schema, an unstated constraint, or a missing mapping between customer language and internal categories. Add targeted detail that closes an observed gap; extra generic wording is not a substitute for required components or behavior. section 1.6.3 section 3.3.2
