# How to Write Development Tickets Your Team Can Build From

> How to write development tickets a Shopify team can build from without follow-up questions: scope, acceptance criteria, and context that actually holds up.

_Published: 2026-07-29 · CommerceCopilot_

## Why vague tickets cost more later

A ticket that says "improve the product page" is not a ticket. It's a placeholder for a conversation that hasn't happened yet, and that conversation happens anyway, just later, more expensively, in a Slack thread the day the developer is supposed to be building.

Learning how to write development tickets that a Shopify team can act on without a follow-up call is one of the most valuable skills on an agency team, and it's rarely taught directly. Most people learn it by writing bad tickets for a year or two and slowly noticing which ones caused rework.

The pattern is consistent across agencies of every size: a ticket missing scope gets built too broadly or too narrowly. A ticket missing acceptance criteria gets marked "done" and bounced back in review. A ticket missing context gets built technically correct and functionally wrong, because the developer solved the words on the ticket instead of the problem behind it.

## What makes a ticket dev ready

A ticket is dev ready when a developer who wasn't in the client call can pick it up, build it, and hand back something that matches what the client actually wanted, on the first pass. That bar rules out most of what passes for a ticket in practice: a one-line Jira title, a screenshot with "like this" typed above it, a paragraph copied straight from a client email.

Three things separate a dev-ready ticket from a placeholder: acceptance criteria that leave no room for interpretation, scope that says what's out as clearly as what's in, and context that explains why the work matters, not just what to build.

### Acceptance criteria that leave no room for interpretation

Acceptance criteria are the test a developer runs against their own work before calling something done. Vague criteria produce vague results: "the cart page should feel more modern" cannot be checked against anything, so it gets checked against the developer's taste, which is rarely the same as the client's.

Specific, testable criteria remove that gap. Instead of "the cart page should feel more modern," write what changes and what the outcome looks like: "Cart drawer shows product image, variant title, and price per line item. Quantity stepper updates the line item total without a page reload. Empty cart state shows a message and a link back to the collection page." Each line is something a developer can check off, and something a reviewer can verify without guessing at intent.

The INVEST framework, a long-standing standard for agile user stories, captures this well: a good story is independent, negotiable, valuable, estimable, small, and testable. The "testable" property is the one tickets skip most often, and it's the one that determines whether a ticket comes back from review clean or with three rounds of "actually, I meant."

### Scope: what's in, what's out, explicitly

Most scope disputes don't come from disagreeing about what's in a ticket. They come from one side assuming something was in scope and the other side never having considered it at all. A ticket that names both sides of that line avoids the argument before it starts.

For a ticket like "add a loyalty tier badge to the product page," the in-scope list might be the badge itself, its placement, and its states (member, non-member, loading). The explicitly out-of-scope list might be the loyalty program's backend logic, the account page changes, and mobile app parity, if those are being handled elsewhere or later. Writing the out-of-scope line takes one sentence and prevents a week of "wait, was that supposed to be part of this?"

### Context: the why, not just the what

A ticket that only states the what gets built correctly and used wrong. A ticket that includes why the client wants the change gives the developer enough judgment to make good calls on the details the ticket didn't anticipate, because every ticket has some.

"Add a size guide modal to the product page" is a what. "Add a size guide modal to the product page; the client's return rate on apparel is high and their support team says most returns are sizing issues" is a what and a why. The second version lets a developer make a better call if, say, the modal doesn't fit cleanly next to the existing size selector on mobile. They know the goal is reducing sizing confusion, not just adding a modal, so they can solve the actual problem instead of the literal instruction.

## A ticket template Shopify teams can reuse

A dev-ready ticket for Shopify work typically includes:

- **Title**: specific enough to identify the change without opening the ticket.
- **Context**: one or two sentences on why this matters to the client, pulled from the brief or discovery notes.
- **Scope**: what's in, what's out, stated as separate lists.
- **Acceptance criteria**: a checklist a developer can verify against their own build.
- **Technical notes**: which template, section, or app is affected, if known. On an Online Store 2.0 theme, this might be as specific as which section file and schema settings are involved, since sections and their settings are what a merchant can reorder and edit without a developer.
- **Dependencies**: any ticket that has to land first, or any open question that blocks a final decision.
- **Design reference**: a link to the Figma frame or asset, not a description of it.

None of this needs to be long. A well-scoped ticket for a single component change might be eight lines total. Length isn't the goal; the goal is that nothing load-bearing is left to be inferred.

## Common ticket mistakes that cause rework

- **Writing the solution instead of the requirement.** "Add a flex container with three columns" tells a developer how, not what outcome to hit, and locks in an implementation before anyone has checked whether it's the right one.
- **Skipping the out-of-scope line.** Leaving scope boundaries implicit is how a two-day ticket becomes a five-day ticket with no change order to show for it.
- **Copying the client's words verbatim without translating them.** Clients describe outcomes in their own language ("make it pop," "feel more premium"). A ticket needs to translate that into something checkable, not just relay it.
- **No acceptance criteria at all, only a description.** A description tells a developer what to build. Acceptance criteria tell them when they're done. Tickets need both.
- **Batching unrelated changes into one ticket.** A ticket touching the cart drawer, the header, and a checkout setting is three tickets wearing one number, and it makes review, QA, and rollback all harder.

## Writing tickets from a messy client brief

Most tickets don't start from a clean spec. They start from a call transcript, a Slack thread, or a two-paragraph email that says roughly what the client wants and leaves the rest to be figured out. The work of turning that into a ticket is translation: pulling out what's actually being asked, flagging what's ambiguous instead of guessing at it, and writing the result in a format a developer can act on without reopening the original conversation.

That translation step is also where a lot of hours quietly disappear, because it usually falls to whoever is senior enough to make the judgment calls, and there's rarely a fast way to do it consistently across every project running at once. CommerceCopilot's Business Analyst agent is built around this handoff: it reads briefs, call transcripts, and connected Slack channels, and drafts a dependency-mapped backlog with acceptance criteria already structured, flagging open questions instead of inventing answers where the source material doesn't say enough. The [brief-to-tickets guide](/docs/your-first-brief-to-ticket-project) walks through the review step before anything gets created in your tracker.

Good tickets also depend on what came before them. A [discovery process that documents goals, constraints, and open questions](/blog/shopify-agency-client-discovery-process) up front gives whoever writes the tickets something solid to translate from, instead of a single rushed call. Ticket quality is downstream of discovery quality; you cannot write a specific, testable ticket from a discovery process that never resolved the ambiguity in the first place.

## A checklist before you hand off a ticket

- Can a developer who wasn't on the client call understand exactly what to build?
- Does it list what's out of scope, not just what's in?
- Are the acceptance criteria specific enough to check off, not just describe?
- Does it explain why the change matters, so the developer can make good judgment calls on details it didn't anticipate?
- Is it one change, not three unrelated changes sharing a ticket number?
- Does it link to the actual design reference instead of describing it secondhand?

## FAQ

### How much detail does a development ticket need?

Enough that a developer who wasn't in the original conversation can build it without asking a clarifying question on anything that affects scope, price, or the client's core requirement. Small tickets can hit that bar in under ten lines. Larger or riskier changes need more, particularly around edge cases and what's explicitly out of scope. Detail should track risk and ambiguity, not a fixed template length.

### What's the difference between a user story and a ticket?

A user story is usually the short, outcome-focused statement of what a user needs and why ("As a returning customer, I want to see my past orders on the account page so I can reorder quickly"). A ticket is the fuller, dev-ready unit built from one or more user stories: scope, acceptance criteria, technical notes, and dependencies included. Many agency teams use the terms loosely, but the story is the intent and the ticket is the buildable spec.

### Who should write tickets: a PM, a BA, or a developer?

Whoever is closest to both the client's intent and the technical constraints, which is why the role is usually called a business analyst rather than a project manager. A pure PM often lacks the technical context to flag scope issues before a developer hits them. A developer writing their own tickets mid-sprint tends to skip the client-facing context, since they already have it in their head. The strongest tickets usually come from someone who translates both directions: business intent into technical scope, and technical constraints back into what's realistic to promise the client.

### Should tickets be written before or after estimating a project?

Rough scope needs to exist before an estimate goes out, since [scoping accuracy depends on knowing what's actually being built](/blog/how-to-scale-shopify-agency-without-hiring). Full, dev-ready tickets with detailed acceptance criteria don't need to exist yet; that level of detail is usually written sprint by sprint, close to when the work actually starts, since requirements that get detailed too far in advance tend to go stale before a developer picks them up.

---
Canonical page: https://www.commercecopilot.ai/fr/blog/how-to-write-development-tickets