Writing tickets for Spec Driven Development: a practical guide for teams and product owners

The user story format, 'As a [role], I want [feature], so that [benefit]', was designed by Kent Beck and Ron Jeffries as a placeholder for a conversation, not a specification document. The three parts were meant to capture who, what, and why at a level of detail sufficient to schedule the work and open a dialogue. The actual details would come out in the conversation between the developer and the person requesting the feature. Story points would estimate the effort. Sprints would create the deadline. The team would figure out the rest.

This worked because development teams were built around human collaboration. A developer could walk over to a product owner, ask what exactly should happen when the user submits an empty form, and get an answer in thirty seconds. The ambiguity in the story was a feature, not a bug: it invited conversation rather than pretending that all questions had been answered in advance.

The challenge Spec Driven Development teams are discovering is that this implicit contract no longer holds. When a developer uses AI tools to implement a feature, the AI does not walk over and ask the PO about edge cases. It implements. It makes assumptions. It produces coherent-looking output that may answer a different question than the one the team actually had. The story card that was once a conversation starter becomes a specification, whether you intended it to be one or not.

This is not a criticism of user stories. They were fit for purpose in the context they were designed for. The context has changed. A ticket that was sufficient to initiate a human conversation is not sufficient to drive an AI implementation. The gap between story intent and implemented behaviour, which used to be bridged by dialogue, now has to be bridged by writing.

Spec Driven Development, in its simplest form, inverts the traditional relationship between specification and implementation. Instead of beginning with an incomplete story and letting implementation decisions emerge through conversation, you write the specification first, in enough detail that the implementation is a predictable consequence. The developer or the AI implements against the spec. The review validates against the spec. The spec is the single source of truth.

A development-ready SDD ticket has to answer several questions that a user story intentionally leaves open. What are all the possible outcomes of this feature, not just the happy path? What happens when the user provides invalid input, when a dependency is unavailable, when concurrent requests arrive simultaneously? What are the explicit constraints on performance, security, and data handling? What is explicitly out of scope, so that the implementation does not creep into adjacent functionality?

This does not mean tickets have to be long. It means they have to be complete. The difference matters. A bloated ticket full of implementation details the team has not agreed on is not a good spec. A concise ticket that names every significant scenario, every error state, and every constraint is. The goal is not volume. It is the absence of assumptions that the developer or the AI would otherwise have to make silently.

There is a useful test for whether a ticket is SDD-ready: can you give it to an AI coding assistant with no additional context and get an implementation that, after review, would meet your definition of done? If the AI has to make significant choices you did not specify, the ticket is not ready. Those choices will either be made incorrectly, or they will require a round of review and correction that the spec should have prevented.

In 2025, Spec-Driven Development moved from an emerging practice to an industry recommendation. Thoughtworks placed it at 'Adopt' level on its Technology Radar, its highest endorsement for engineering techniques. The same year, GitHub released Spec Kit, an open-source toolkit that formalises the specify-plan-build workflow for use with AI coding assistants, and Amazon Web Services launched Kiro, a development environment built on the premise that specifications, not conversations, should drive AI implementation. Martin Fowler at ThoughtWorks and Addy Osmani at Google are among the senior engineering voices who have published extensively on why structured specifications matter for teams working with AI tools.

The contrast these practitioners draw is with 'vibe coding': informal, conversational AI-assisted development where the developer describes what they want and iterates without a written spec. Vibe coding produces output quickly. It also produces output whose behaviour depends on assumptions neither the developer nor the AI has made explicit. For weekend projects and throwaway prototypes, that trade-off may be acceptable. For production software with error handling, security constraints, and team-wide readability requirements, it is not. The structured ticket approach described in this article is the alternative that the current tooling ecosystem is built around.

Practitioners writing about SDD in 2025 also describe three levels of engagement, which offer a useful map for where your team sits today and where to aim next.

Most teams working with AI tools today sit between Level 1 and Level 2. The exercises at the end of this article are designed to build the muscle for Level 2 work: tickets precise enough to drive implementation and meaningful enough to keep. The progression to Level 3 is a longer journey, and the tooling is still maturing. The thinking skills that get you there are the same at every level.

Behaviour Driven Development (BDD), formalised by Dan North in 2003, introduced Gherkin as a structured, human-readable language for writing behavioural specifications. The Given-When-Then format describes system behaviour in terms a non-technical stakeholder can read and a test automation framework can execute.

This is a genuine contribution to specification quality. Gherkin forces the team to describe behaviour in observable, testable terms. It makes the happy path explicit. It creates executable documentation that can double as automated test criteria. For teams practising BDD well, the scenarios written before implementation serve as both the specification and the test suite.

Where Gherkin falls short as a complete SDD ticket is in scope and completeness. A Gherkin scenario describes one path through the system. Non-functional requirements such as response time limits, security constraints, and concurrency handling are awkward to express in Given-When-Then and are frequently omitted. The out-of-scope declaration, which is one of the most valuable elements of a good spec, has no natural home in Gherkin. The business context that helps implementers make judgment calls at the boundaries of the spec is typically absent.

SDD tickets and Gherkin are not in competition. A well-written SDD ticket can include Gherkin scenarios for the key behavioural paths while surrounding them with the context, constraints, and explicit exclusions that Gherkin does not natively provide. Think of Gherkin as a precise tool for expressing individual scenarios, and the SDD ticket as the broader container that makes those scenarios meaningful.

The best way to understand the format is through a side-by-side comparison. Both cards below describe the same feature: password reset via email token.

The user story can be written in thirty seconds. The SDD ticket requires thought. But the thought it requires is thought the team would have to do anyway. The only question is whether it happens before implementation or after, in a review cycle or in a production incident. The SDD ticket front-loads clarity. The user story defers it.

The password reset example above illustrates the format. Here is a closer look at what each part actually asks of the writer, why it exists, and the most common mistakes teams make when filling it in.

These six parts are not a rigid template. Some tickets need many error states; some need almost none. Constraints may be obvious from context. What matters is not the format but the intent: every question a developer or AI would otherwise have to answer silently should be answered explicitly in the ticket before work begins.

Table filters appear in almost every backlog. The user story typically reads: 'As a user, I want to filter the orders list so I can find what I need.' Here is what a development-ready ticket looks like for the same feature.

File upload hides a surprising number of decisions behind a short user story. 'As a user, I want to upload a profile photo' typically masks at least fifteen open questions about accepted formats, size limits, processing, and failure handling. Here is the spec that closes them.

Notification triggers look simple until you consider idempotency, opt-out handling, and failure recovery. A story that reads 'As a user, I want to be notified when my order ships' opens questions about timing, deduplication, and what happens when the email service is unavailable. Here is the spec.

Whether 'delete' means permanent removal, reversible archival, or a two-stage soft-delete determines almost every implementation decision, yet the user story rarely says which. Here is a spec for the most common case: deletion that needs to be reversible.

A common objection to SDD ticket writing is that it places an unfair burden on the product owner. If the PO is non-technical, how can they be expected to specify error handling, token expiry windows, and security constraints? The short answer is: they do not have to. The SDD ticket has a clear division of labour, and most of what a non-technical PO does well maps directly onto the parts of the ticket that matter most.

What a non-technical PO writes is the problem statement and user context. This is the why behind the feature: the frequency of the problem, the population it affects, the cost of not solving it. No one in the room knows this better than the PO. For the password reset example, the PO is the person who knows that support handles 30 password tickets a week, that there is a regulatory requirement around email enumeration, and that mobile users are the primary affected segment. This context shapes every implementation decision that follows.

The PO also writes the business rules they already know. In the password reset case, the PO might know that legal has said the system must not reveal registered email addresses, that the link must not be usable more than once, and that the support team's SLA requires the email to arrive within a minute. These are business rules, not technical specifications. They belong in the ticket. The PO owns them.

What the PO does not write is the translation of those business rules into technical constraints. The requirement 'links must not be reusable' translates to 'using the reset link immediately invalidates it.' The requirement 'the link must not remain valid indefinitely' translates to 'expires after 30 minutes.' The requirement 'do not reveal registered emails' translates to 'identical response regardless of whether the email is found.' A developer or a technical lead does that translation. The PO reviews it to confirm it is faithful.

The collaborative model that works well is this: the PO writes the problem statement, user context, and business rules on the ticket in plain language. In a focused session of no more than 30 minutes, a developer or tech lead reads those notes and writes the acceptance criteria, error states, and constraints. The PO then reviews the resulting spec and confirms that it captures their intent. This is not more work than a traditional refinement session. It is the same work, done more explicitly, producing an artefact that outlasts the conversation.

This model also has an important quality-checking property. When the PO reads the translated spec, they frequently catch something they had not thought through. The acceptance criterion 'identical response regardless of whether the email is found' might prompt them to confirm the regulatory interpretation with legal. The error state 'rate limit reached, show how many minutes remain' might prompt them to question whether that information should be visible at all. The spec reveals the implications of the requirement in a way the original business rule does not. That is not a failure of the process. It is the process working.

The shift from user stories to SDD tickets is not primarily a writing skill. It is a thinking skill: the ability to make implicit assumptions explicit before implementation. The following three exercises are designed to build that skill in a team context, using work you are already doing. Each can be run in a single session with no preparation beyond choosing a real ticket from your backlog.

A note on expectations: the first SDD ticket your team writes will not be a good one, and neither will the second. Writing precise specifications is a skill, and it improves with deliberate practice. What changes quickly is the team's ability to see ambiguity, to notice when a requirement leaves open a question the implementation will have to answer. That awareness changes how stories are written, how they are discussed in refinement, and how developers interact with AI tools when they pick the ticket up.

The teams that make this transition well are not the ones that adopted a rigid template and enforced it from day one. They are the ones that started with these exercises, built a shared vocabulary for what a complete specification looks like, and let their own format emerge from that vocabulary. The goal is not a better template. It is a team that thinks differently about what it means to be ready to build.