Develop and review / Deliver a change
中文

Deliver a change

Turn a Jira ticket into a tested change ready for review.

Updated 5 Nov 2026View as markdown
On this page

1. Understand the ticket

Prompt
Read [Jira key or URL] through the connected Jira MCP or authenticated acli, including description, acceptance criteria and comments.
If access is unavailable, ask for pasted details. Read the repository instructions and trace the affected flow.
Propose the smallest change and the checks that prove it. List unclear business rules, permissions or data decisions as questions.
Do not change code yet.
  • Bring the project context from Start on a project and the agreed branch plan.
  • For a simple edit, a brief approach is enough. Discuss changes to business rules, permissions or data with the person responsible for the requirement first.
  • Keep the PR to one purpose. Split when it makes verification, rollout or recovery easier; a line count alone does not establish reviewability.
Jira connection reference

Use a connected Jira MCP or authenticated Atlassian CLI.

acli jira workitem view ENG-123 --fields '*all' --json
ExampleENG-123 · Export filtered orders

Merchant admins can export the currently filtered orders as CSV. The file is built in the background, and the admin is notified when it is ready. Fix version: 2.8.0.

  • Include order reference, date and total.
  • Exclude customer contact details and other merchants’ orders.
  • Empty results return headers only.
  • A retried export produces one file and one notification.
  • Scheduled exports are out of scope.

2. Implement the change

Prompt
Implement the agreed change for [Jira key] on [ticket branch], with tests for each acceptance criterion.
Update the docs and agent instructions this change makes wrong. Keep plans and notes out of the repository.
Report the files changed, the tests added and any change to the agreed behaviour or risk.
Do not push or open a PR yet.
  • Docs change in the same PR as the behaviour they describe, so closeout is a check rather than a rewrite.
  • Backend changes stay backwards compatible. Existing clients keep working, including every installed app version still allowed to run. Add fields and endpoints; change or remove them only after no supported client depends on them.

    CautionAn installed mobile build cannot be recalled, and users update late. The forced-update setting decides which versions are still supported.

  • Check that each acceptance criterion has a test and that the diff touches only this ticket’s files.
  • Keep the agent on synthetic data and within its access: production and destructive actions wait for your go-ahead.
  • Track unrelated defects in their own tickets instead of fixing them in this change.
  • If a discovery changes the agreed behaviour or risk, agree the change with the person responsible for the requirement first.
  • A new doc needs an entry in the docs index.
  • Apply the safeguards relevant to the change: access and data, database changes, money and rewards, jobs and external calls, or SMS and paid endpoints.

3. Verify the result

Scenario: the agent says ENG-123 is done and all tests pass.

Bad prompt
Great, all tests pass. Open the PR.
Better prompt
Verify this change against the ticket’s acceptance criteria using synthetic data.
Run the relevant checks and exercise the affected flow. For a bug fix, show the regression test failing before the fix and passing after it.
Report evidence for each criterion, commands, the tested commit and any gaps. Fix the causes of failed checks without weakening safeguards.
Do not push or open the PR yet.

Why: tests the agent wrote can share the implementation’s wrong assumption. Evidence for each acceptance criterion checks the behaviour itself. See Code review.

  • Check the evidence against the ticket; inspect anything the AI agent could not verify.
  • Changing a safeguard needs a stated reason and reviewer agreement.

For ENG-123, have the AI agent verify:

Expected behaviour Evidence
Correct CSV Order reference, date and total match the filtered synthetic orders; no customer contact details.
Merchant isolation Another merchant’s orders, downloads and jobs are inaccessible.
Admin permission A non-admin user from the correct merchant cannot export or download.
Empty results An empty export has headers only.
Retries After a worker restart, the export completes with one file and one notification.
Existing behaviour UI filters still work.

4. Open a reviewable PR

Prompt
Check the final diff for [Jira key] for defects, unrelated changes and unexpected files. Stop and report any you find.
If the diff is clean, push [ticket branch] and open a PR into [target branch]. Describe why the change exists, link the ticket and its acceptance criteria, and give the evidence for each criterion, the checks with the tested commit, what was not verified and how to undo the change.
Do not merge.
  • Run tests and lint in CI for the change under review. Local success does not prove the shared build environment works.
  • Explain why the change exists. Link the ticket and its acceptance criteria so the reviewer can judge the outcome.
  • State what was not verified and why. The approver needs the gaps to make an informed decision.

PR description example

ENG-123: Export filtered orders

Why: Merchant admins need a CSV of the orders they are viewing.
Evidence: Fields, filters, empty results, retries, merchant isolation and admin permissions checked with synthetic users from two merchants.
Checks: [CI run] · [commands and results] · commit [SHA].
Gap: Production-volume performance is unverified.
Follow-up: [Jira link], owned by [name]; resolve before release.
Recovery: Pause the export queue, then redeploy the previous release; the additive exports table stays.