Turn a vague feature request into a testable engineering plan

A request such as “make exports better” looks small until an assistant adds background jobs, invents a file format, and changes the permissions model. The code may compile while solving the wrong problem. The failure begins before implementation: nobody established what users are trying to finish or which behavior would count as an improvement.

Consider an illustrative reporting application where customers currently download a CSV from a table. The proposed improvement is faster exporting. This article uses that example to develop a plan. The timings and product rules below are requirements to decide, not measured results from an actual service.

Start with the blocked user journey

Write the current journey in ordinary language. A signed-in account member filters orders, clicks Export, waits without feedback, and sometimes clicks again. The problem might be perceived delay, duplicate requests, missing filters, or the amount of data exported. “Faster” does not tell you which one matters.

Ask for the observed symptom, its frequency, and the consequence. A screenshot of a spinner is useful evidence of presentation but does not establish that the database is slow. A network trace showing two export requests after two clicks suggests a different fix. Capture one specific example, including account role, filters, approximate dataset size, and expected output.

A good initial statement is: “An account member cannot tell whether the export request was accepted and can accidentally start another export.” That statement already narrows the likely work. It leaves room to investigate latency without promising a new architecture.

Separate decisions from assumptions

Create three short groups: confirmed behavior, open product decisions, and implementation assumptions. Confirmed behavior might include CSV output and account-scoped orders. Open decisions include whether repeated clicks should reuse a running export and whether a completed file should expire. Assumptions include a maximum result size and availability of a background worker.

Do not let an AI answer an open product question just because it can propose a reasonable default. Ask it to identify missing decisions, then mark which answers come from the product owner and which remain provisional. For example, “exports include all filtered records” and “exports include only visible rows” are both implementable and produce very different outcomes.

Give each unresolved item an owner and consequence. If the export cannot ship safely without a permission rule, resolve that rule before coding. If button copy can be adjusted later without changing the contract, choose a provisional phrase and continue. This distinguishes genuine blockers from inexpensive choices.

Write acceptance examples before tasks

Translate the journey into examples that someone can execute. With a permitted account member and a date filter, clicking Export should send one request containing that filter and show an accepted state. A second click while the same operation is pending should not start a second operation. An unauthorized account should receive a denied response and no file.

Include failure behavior. If file creation fails, the page should keep the selected filters and offer a deliberate retry. If the session expires, the user should receive an authentication prompt rather than an unexplained empty file. Empty results should produce the agreed empty export or a clear no-results message.

Avoid criteria such as “the code is clean” or “the export is optimized.” They are review preferences rather than observable acceptance conditions. Performance criteria need a workload, environment, and measurement method. Until those exist, describe responsiveness separately from actual processing time.

Choose the smallest coherent change

The smallest fix might be a pending state and duplicate-click protection around the current endpoint. It might instead require an asynchronous job if the current request cannot finish within the hosting limit. Diagnose the limiting condition before choosing between them.

A useful plan records the current request path, the proposed change, and the behavior preserved. For a synchronous fix, preserve CSV columns, account authorization, and filter semantics. Change only request feedback and repeated submission handling. For a job-based fix, explicitly add job identity, status retrieval, expiration, and download authorization.

Split tasks by completed behavior: first reproduce duplicate submission, then enforce the operation contract, then implement feedback, then verify failures. Avoid dividing solely into “frontend” and “backend” if neither part can be checked independently. A contract example lets both sides move while keeping integration reviewable.

Give the assistant a bounded brief

Provide the relevant route, export function, authorization helper, and existing tests. Include the acceptance examples and forbidden scope, such as changing billing or introducing a queue without evidence. Ask the assistant to identify inconsistencies before it edits files.

An illustrative prompt is: “Trace the existing export path. Report the files that own filtering, authorization, and submission. Propose the smallest change satisfying these examples. Label unresolved requirements. Do not implement until the contract is coherent.” This is useful because the assistant can search and summarize connections while the engineer retains responsibility for the product decisions.

After the plan is accepted, request implementation in one bounded slice. Require the assistant to report changed behavior, verification performed, and remaining limitations. The related guide on keeping tasks small explains how to avoid a plan turning into several loosely related projects.

Verify the plan against reality

Walk each acceptance example through the actual application. Check that named files exist, that the endpoint accepts the proposed filter shape, and that authorization happens on the server. A plan referencing a nonexistent helper has already failed a basic evidence check.

Run the duplicate-click reproduction before and after the change. Inspect the request count, response status, file contents, and visible pending state. Test an empty result, permission denial, and recoverable failure. If a background worker is proposed, verify its presence in the deployment rather than relying on local infrastructure.

Record what was not tested. A tiny development dataset cannot establish production export performance. A mock response cannot prove file creation or storage permissions. The plan should expose these gaps so deployment checks can address them instead of treating passing component tests as complete evidence.

Keep planning proportional

Not every small UI improvement needs a lengthy specification. A button label change can use a few acceptance sentences. A feature with money movement, permissions, or asynchronous work needs more precise contracts because hidden assumptions become expensive.

The plan is a working artifact, not a promise that discovery is finished. If implementation reveals a conflicting filter rule, update the examples and scope before proceeding. Preserve the reason for important decisions so reviewers can distinguish deliberate compromises from omissions.

A successful plan makes the next action clear and the final result checkable. It also makes stopping reasonable: if duplicate submission is fixed and feedback is understandable, an unmeasured architecture rewrite can remain a separate proposal.

Sources

GitHub Copilot best practices supports explicit prompts and verification of suggestions.

Anthropic: Building effective agents discusses simple workflows and increasing complexity when needed.