Specify the result. Constrain the patch.
Ambiguity becomes code unless it is resolved.
A generation specification should let another engineer tell whether the result is correct. Describe the behavior in terms of inputs, outputs, and invariants. Add implementation constraints only when they protect compatibility or reflect a real convention in the repository.
Make a concrete behavior table
For a list endpoint, define the default ordering, accepted cursor shape, and response when the cursor is invalid. Mention whether an empty result is normal. These cases are more useful than an instruction to make the implementation production-ready, because each one can be checked against actual behavior.
Separate requirements from suggestions
Preserving a public response type may be required. Reusing a nearby helper may be preferred if inspection confirms it is suitable. Label that distinction so the assistant does not force an inappropriate abstraction into place. Request a small patch and evidence for the important cases, with unresolved assumptions called out before implementation.
- INPUT
- Optional cursor; validated at the boundary.
- OUTPUT
- Stable ordering and the existing response shape.
- EVIDENCE
- Empty page, valid cursor, invalid cursor.
SPECIFICATION FRAGMENTS
Add cursor handling to the existing list endpoint. Keep the public response type unchanged. Use the current validation boundary. Explain any assumptions before editing.
No cursor -> first page in the documented order. Valid cursor -> next page without duplicates. Invalid cursor -> existing validation error shape. No matches -> successful empty result.
Report changed files and compatibility decisions. List the checks actually executed and their results. Identify any case that remains unverified. Keep follow-up proposals separate from this patch.
A long prompt cannot compensate for a missing behavioral decision.