A useful task brief states the behavior to change, the evidence that defines the problem, the constraints that must remain true, and the checks that will demonstrate success. It also says where the agent should stop if the work turns out to require a different decision.
You do not need to prescribe every implementation step. You need to make the result distinguishable from a plausible-looking patch.
The brief belongs with the task. Repository instructions should carry recurring guidance; an issue-specific reproduction, temporary constraint, or rollout decision needs a home that can change and close with the work.
Start with the observed behavior
Consider this request:
Fix pagination. It breaks on bad input. Keep it backward compatible and add tests.
The agent cannot tell what “bad” means, which entry point fails, or which existing behavior matters. It might clamp values, reject them, return an empty result, or change the default. Each could look reasonable and still violate the product's intended contract.
A stronger starting point separates observation from interpretation:
In the synthetic catalog API,
parse_limit("-1")returns-1. The request layer then passes that value to the query. The intended contract accepts decimal ASCII digits from 1 through 100 and defaults to 25 only when the value is absent.
The first sentence says what was observed. The second specifies desired behavior. If the contract has not actually been agreed, label it as a proposed decision instead of hiding it inside an implementation request.
GitHub's guidance for Copilot cloud agent calls for well-scoped tasks with acceptance criteria. The example below applies that principle to an original, synthetic task; it is not a claim that a particular wording guarantees a successful agent run.
Turn adjectives into observable constraints
“Robust,” “fast,” and “backward compatible” need a reference point.
For compatibility, identify the users or callers whose behavior must remain supported. For performance, name the workload, environment, and measurement method before setting a target. For security, identify the boundary and the undesired operation rather than saying “make it secure.”
In the pagination example, compatibility could mean that a missing value still produces 25 and strings such as "01" remain accepted as 1. It need not mean preserving accidental acceptance of "-1".
| Vague requirement | Verifiable replacement |
|---|---|
| Handle invalid input gracefully | Raise the documented ValueError before the query function is called |
| Keep the default | parse_limit(None) returns 25 |
| Preserve valid values | "1", "01", "25", and "100" produce the corresponding integers |
| Reject bad values | Empty, signed, whitespace-padded, non-ASCII, zero, and values above 100 are rejected |
| Keep the change small | Preserve the public function signature and the query layer's interface |
This table encodes product choices. Another API may intentionally accept whitespace or clamp large values. A brief should expose that difference so a reviewer can challenge it before code solidifies around the assumption.
A complete brief for the example
The following is a task-specific template filled with concrete requirements:
Outcome
Reject invalid page limits before a query runs, while preserving the
existing default and accepted decimal values.
Starting evidence
parse_limit("-1") currently returns -1.
The parser is in limits.py; tests use Python's unittest module.
These paths describe the synthetic example, not your repository.
Input contract
The parser accepts str or None.
None means the parameter is absent and returns 25.
A provided string must contain only ASCII decimal digits and
represent a number from 1 through 100 inclusive.
Leading zeros are accepted. No trimming or clamping.
Constraints
Preserve the function signature.
Do not change the query layer, add dependencies, or alter other
request parameters.
Acceptance
Cover default, lower and upper bounds, and leading zeros.
Reject "", "0", "-1", "+2", " 2", "2 ", "101", and "2.0".
Reject non-ASCII numeric characters.
Run the relevant tests and the existing suite.
Report actual commands and results, including unavailable checks.
Decision boundary
If a real caller relies on behavior this contract would reject,
report that caller and the conflict before changing the public rule.
Delivery
Provide the patch, a short behavioral explanation, verification
evidence, and any unresolved issue. Do not publish or deploy.
This is deliberately more specific about behavior than implementation. It does not require a regular expression, a helper class, or a particular control-flow pattern. Several implementations may satisfy the contract.
The stop condition is narrow. It asks for a decision only when newly discovered evidence changes compatibility. It does not require a question about each ordinary editing choice.
Supply starting points without pretending they are complete
File paths, error messages, a failing request, and the command used to reproduce it can reduce unnecessary searching. They are leads, not proof that all relevant code lives there.
State what has already been checked. “The parser is probably responsible” is different from “this command reproduces the failure in the parser.” Do not turn a hypothesis into a constraint that prevents investigation.
Anthropic's context engineering article discusses combining concise guidance with information retrieved when needed. For a task brief, that suggests linking the contract or fixture at the point it becomes relevant instead of pasting every subsystem document into the request.
Give references a purpose: “Read the export contract before changing field names” tells the agent why the document matters. “Read all docs” provides no useful selection rule.
Keep real secrets and customer records out of reproduction examples. A synthetic input should reproduce the relevant property without reproducing the private data.
Distinguish acceptance from implementation-shaped tests
An acceptance check should reject the wrong behavior even if the implementation looks different from the one you expected.
For the parser, asserting that "-1" is rejected checks a public result. Asserting that the source contains a particular regular expression checks your preferred implementation. The latter might pass while a caller bypasses validation, or fail against a correct alternative.
A full task may require more than unit checks. If the requirement is “reject before a query runs,” test the request path with a fake query dependency and verify that it was not called for invalid input. A parser-only test cannot establish that integration property.
Use the project's established commands after checking their working directory and prerequisites. Python's unittest discovery documentation explains one command style, but copying it into a JavaScript repository would not make it appropriate.
The brief above is illustrative. This article does not claim an agent executed it or that it improved task success.
Leave a truthful completion contract
Ask for enough evidence to assess the result: behavior changed, important files, checks actually run, observed results, and limitations. Avoid demanding a generic “all tests passed” sentence.
The agent may finish implementation while an integration service is unavailable. A truthful report can say the narrow tests passed and the integration check did not run. That is a reviewable state with a specific limitation, not an excuse to imply complete validation.
When scope changes, revise the brief and preserve the decision. Do not let a growing conversation silently redefine success while the original acceptance criteria remain unchanged.
A quick test of the brief is to hand it to someone who has not seen the discussion. If they can explain the desired behavior, identify a failing counterexample, and tell when to stop, the task has enough structure to begin.
Research note: sources reviewed October 28, 2026. The pagination brief is a synthetic specification example, not an empirical prompt-effectiveness study.
