# Deliver a change

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

Develop and review · /deliver-a-change/ · 2026-11-05

## 1. Understand the ticket

**Prompt**

```text
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](/new-project/) and the agreed [branch plan](/branching-strategy/).
- 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.

* **PR-1** (medium risk; checked by code review): **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](https://developer.atlassian.com/cloud/rovo-mcp/) or authenticated [Atlassian CLI](https://developer.atlassian.com/cloud/acli/reference/commands/jira-workitem-view/).

```sh
acli jira workitem view ENG-123 --fields '*all' --json
```

> **Example: ENG-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**

```text
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.
```

- **REL-2** (medium risk; checked by code review): **Docs change in the same PR as the behaviour they describe,** so closeout is a check rather than a rewrite.
- **API-1** (high risk; checked by code review): **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.

  Caution: An 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](/security/#limit-the-agents-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](/release-mgmt/#r-rel-7).
* Apply the safeguards relevant to the change: [access and data](/security/), [database changes](/migrations/), [money and rewards](/value-abuse/), [jobs and external calls](/jobs/), or [SMS and paid endpoints](/otp/).

## 3. Verify the result

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

**Bad prompt**

```text
Great, all tests pass. Open the PR.
```

**Better prompt**

```text
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](/code-review/#r-ai-3).

- 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**

```text
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.
```

- **CI-1** (high risk; checked by CI): **Run tests and lint in CI for the change under review.** Local success does not prove the shared build environment works.
- **PR-2** (medium risk; checked by code review): **Explain why the change exists.** Link the ticket and its acceptance criteria so the reviewer can judge the outcome.
- **PR-5** (medium risk; checked by code review): **State what was not verified and why.** The approver needs the gaps to make an informed decision.

_PR description example_

```text
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.
```

Next: Hand the PR, its evidence and its stated gaps to [Code review](/code-review/).