The Art of Agile Development: Stories

The second edition is now available! The Art of Agile Development has been completely revised and updated with all new material. Visit the Second Edition page for more information, or buy it on Amazon.


Whole Team

We plan our work in small, customer-centric pieces.

Stories are not requirements.

Stories may be the most misunderstood entity in all of XP. They're not requirements. They're not use cases. They're not even narratives. They're much simpler than that.

Release Planning

Stories are for planning. They're simple, one-or-two line descriptions of work the team should produce. Alistair Cockburn calls them "promissory notes for future conversation"1. Everything that stakeholders want the team to produce should have a story:

1, accessed 30 May 2007.

  • "Warehouse inventory report"

  • "Full-screen demo option for job fair"

  • "TPS report for upcoming investor dog-and-pony show"

  • "Customizable corporate branding on user login screen"

Some people find that using a template helps them write good stories. For example, [Cohn] recommends using the template "As a (role) I want to (goal) so that (reason)".

Incremental Requirements

This isn't enough detail for the team to implement and release working software, nor is that the intent of stories. A story is a placeholder for a detailed discussion about requirements. Customers are responsible for having the requirements details available when the rest of the team needs them.

Although stories are short, they still have two important characteristics.

  1. Stories represent customer value and are written in the customers' terminology. (The best stories are actually written by customers.) They describe an end-result that the customer values, not implementation details.

  2. Stories have clear completion criteria. Customers can describe an objective test that would allow programmers to tell when they've successfully implemented the story.

The following examples are not stories:

  • "Automate integration build" does not represent customer value.

  • "Deploy to staging server outside of the firewall" describes implementation details rather than an end-result, and it doesn't use customer terminology. "Provide demo that customer review board can use" would be better.

  • "Improve performance" has no clear completion criteria. Similarly, "Make it fast enough for my boss to be happy" lacks objective completion criteria. "Searches complete within one second" is better.

Story Cards

Write stories on index cards.

I prefer 3x5-inch cards because they fit into my pocket.

This isn't the result of some strange Ludditian urge on the part of XP's creators; it's a deliberate choice based on the strengths of the medium. You see, physical cards have one feature that no conglomeration of pixels has: they're tactile. You can pick them up and move them around. This gives them power.

Release Planning

During release planning, customers and stakeholders gather around a big table to select stories for the next release. It's a difficult process of balancing competing desires. Index cards help prevent these disputes by visually showing priorities, making the scope of the work more clear, and directing conflicts towards the plan rather than personalities.

Informative Workspace

Story cards also form an essential part of an informative workspace. After the planning meeting, move the cards to the release planning board—a big, six-foot whiteboard, placed prominently in the team's open workspace (see Figure). You can post hundreds of cards and still see them all clearly. For each iteration, place the story cards to finish during the iteration on the iteration planning board—another big whiteboard; see Figure—and move them around to indicate your status and progress. Both of these boards are clearly visible throughout the team room and constantly broadcast information to the team.

Use index cards to be more responsive to stakeholder suggestions.

Index cards also help you be responsive to stakeholders. When you talk with a stakeholder and she has a suggestion, invite her to write it down on a blank index card. I always carry cards with me for precisely this purpose. Afterwards, take the stakeholder and her card to the product manager. They can walk over to the release planning board and discuss the story's place in the overall vision. Again, physical cards focus the discussion on relative priorities rather than contentious "approved / disapproved" decisions.


If the product manager and stakeholder decide to add the story to the release plan, they can take it to the programmers right away. A brief discussion allows the programmers to estimate the story. Developers write their estimate—and possibly a few notes—on the card, and then the stakeholder and product manager place the card into the release plan.

Index cards are simpler and more effective than computerized tools.

Physical index cards enable these ways of working in a very easy and natural way that's surprisingly difficult to replicate with computerized tools. Although you can use software, index cards just work better: they're easier to set up and manipulate, make it easier to see trends and the big picture, and allow you to change your process with no configuration or programming.

Most people are skeptical about the value of index cards at first, so if you feel that way, you're not alone. The best way to evaluate the value of physical story cards is to try them for a few months, then decide whether to keep them.


The Planning Game

Stories need to be customer-centric. Write them from the on-site customers' point of view and make sure that they provide something that customers care about. On-site customers are in charge of priorities in the planning game, so if a story has no customer value, your customers won't—and shouldn't—include it in the plan.

A good way to ensure that your stories are customer-centric is to ask your customers to write the stories themselves.

One practical result of customer-centric stories is that you won't have stories for technical issues. There should be no "Create a build script" story, for example—customers wouldn't know how to prioritize it. Although programmers can tell customers where the technical stories belong in the plan, that disrupts the balance of power over the scope of the project and can leave customers feeling disenfranchised.

Instead, include any technical considerations in the estimate for each story. If a story requires that the programmers create or update a build script, for example, include that cost when estimating for that story.

Incremental Design And Architecture

Including technical costs in stories, rather than having dedicated technical stories, requires incremental design and architecture.

Customer-centric stories aren't necessarily always valuable to the end-user, but they should always be valuable to the on-site customers. For example, a story to produce a trade-show demo doesn't help end-users, but it helps the customers sell the product.

Splitting and Combining Stories

Stories can start at any size, but it is difficult to estimate stories that are too large or too small. Split large stories; combine small ones.

Select story sizes such that you complete four to ten each iteration.

The right size for a story depends on your velocity. You should be able to complete four to ten stories in each iteration. Split and combine stories to reach this goal. For example, a team with a velocity of ten days per iteration might split stories with estimates of more than two days, and combine stories that are less than half a day.

Combining stories is easy. Take several similar stories, staple their cards together, and write your new estimate on the front.

Splitting stories is more difficult, because it tempts you away from vertical stripes and releasable stories. It's easiest to just create a new story for each step in the previous story. Unfortunately, this approach leads to story clumps. Instead, consider the essence of the story. Peel away all of the other issues and write them as new stories. [Cohn] has an excellent chapter on how to do this in his book Agile Estimating and Planning. He summarizes various options for splitting stories:

  • Split large stories along the boundaries of the data supported by the story.

  • Split large stories based on the operations that are performed within the story.

  • Split large stories into separate CRUD [Create, Read, Update, Delete] operations.

  • Consider removing cross-cutting concerns (such as security, logging, error handling, and so on) and creating two versions of the story: one with and one without support for the cross-cutting concern.

  • Consider splitting a large story by separating the functional and nonfunctional [performance, stability, scalability, and so forth] aspects into separate stories.

  • Separate a large story into smaller stories if the smaller stories have different priorities.

Special Stories

Most stories will add new capabilities to your software, but any action that requires the team's time but is not a part of normal work needs a story.

Documentation Stories


XP teams need very little documentation to do their work (see Documentation), but you may need the team to produce documentation for other reasons. Create documentation stories just like any other: make them customer-centric and make sure you can identify specific completion criteria. An example of a documentation story is "Produce user manual".

"Non-Functional" Stories

Performance Optimization

Performance, scalability, and stability—so-called non-functional requirements—should be scheduled with stories too. Be sure that these stories have precise completion criteria. See Performance Optimization for more.

Bug Stories

No Bugs
"Done Done"

Ideally, your team will fix bugs as soon as they find them, before declaring a story as "done done". Nobody's perfect, though, and you will miss some bugs. Schedule these bugs with story cards: "Fix multiple-user editing bug". Schedule them as soon as possible to keep your code clean and reduce your need for bug-tracking software.

Bug stories can be difficult to estimate. Often, the biggest timesink in debugging is figuring out what's wrong, and you usually can't estimate how long that will take. Instead, provide a time-boxed estimate. "We'll spend up to a day investigating this bug. If we haven't fixed it by then, we'll schedule another story."

Spike Stories

Spike Solutions

Sometimes programmers won't be able to estimate a story because they don't know enough about the technology required to implement the story. In this case, create a story to research that technology. An example of a research story is "Figure out how to estimate 'Send HTML' story". Programmers will often use a spike solution (see Spike Solutions) to research the technology, so these sorts of stories are often called spike stories.

Word these stories in terms of the goal, not the research that needs to be done. When programmers work on a research story, they only need to do enough work to make their estimate for the real story. They shouldn't try to figure out all of the details or solve the entire problem.

Programmers can usually estimate how long it will take to research a technology even if they don't know the technology in question. If they can't even estimate how long the research will take, timebox the story as you do with bug stories. I find that a day is plenty of time for most spike stories, and half a day is sufficient for most.


Other than spike stories, you normally don't need to schedule time for the programmers to estimate stories—you can just ask them for an estimate at any time. It's part of the overhead of the iteration, as are support requests and other unscheduled interruptions. If your programmers feel that estimating is too much of an interruption, try putting new story cards in a pile for the programmers to estimate when it's convenient.

Sometimes you'll have a large number of new stories to estimate. In this case, it might be worth creating a story card for estimating those stories.


Like estimating, most meetings are part of the normal overhead of the iteration. If you have an unusual time commitment, such as training or an day-long off-site, you can reserve time for it with a story.

Architecture, Design, Refactoring, and Technical Infrastructure

Incremental Design And Architecture

Don't create stories for technical details. Technical tasks are part of the cost of implementing stories and should be part of the estimates. Use incremental design and architecture to break large technical requirements into small pieces that you can implement incrementally.


Are index cards really more effective than computerized tools? What about reporting?

See our discussion of reporting (Reporting) for more information.

What about backups? Won't the cards get lost?

If you exercise reasonable care, you're unlikely to lose cards. The only time I've seen a team lose their cards was when they created them and then left them in an ignored pile somewhere on their boss's desk for six months.

That said, there's always the possibility of fire or other disaster. If the risk of losing cards is too great for you, consider taking a digital photo of the release planning board every week or so. An eight megapixel camera has sufficient resolution to capture a six-foot whiteboard and all of the detail on the cards.

Why do you recommend sizing stories so that we can complete four to ten stories per iteration?

If you only have a few stories in an iteration, it's harder to see that you're making progress, which increases the risk that you won't see problems in time to correct them. In addition, if something goes wrong and you can't finish a story, it will represent a large percentage of your work. Too many stories, on the other hand, increases your planning and estimating burden. Each story becomes smaller, making it harder to see the big picture.

An average of six stories per iteration leads to a three-month release plan (the maximum I recommend) consisting of 78 stories. That's a nice number. It gives you flexibility in planning without overwhelming you with details.

Our customers understand programming. Can we create programmer-centric technical stories?

It's much more difficult to create customer-centric stories than programmer-centric stories, so it's tempting to find excuses for avoiding them. "Our customers don't mind if we have programmer-centric stories" is one such excuse. Try to avoid it.

Even if your customers really do have the ability to prioritize programmer-centric stories, customer-centric stories lead to better plans. Remember, your goal is to create stories that allow you to release the software at any time. Programmer-centric stories usually don't have that property.

If your customers are programmers—if you're writing software for programmers, such as a library or framework—then your stories should use a programmer-centric language (see Ubiquitous Language). Even so, they should reflect your customers' perspective. Create stories about your customers' needs, not your plans to fulfill their needs.

How can we encourage stakeholders to use stories for requesting features?

When a stakeholder asks you for a feature, take out an index card and invite him to write it down so it can be scheduled. For electronic requests, a customer should follow up, either by speaking to the requester in person or creating the story card himself.

If stakeholders refuse to use stories, the product manager can manage this relationship by providing stakeholders with what they want to see and translating stakeholders wishes into stories for the team.


When you use stories well, the on-site customers understand all of the work that they approve and schedule. You work on small, manageable, and independent pieces and can deliver complete features frequently. The project always represents the best possible value to the customer at any point in time.


Stories are no replacement for requirements. You need another way of getting details, whether through expert customers on-site (the XP way) or a requirements document (the traditional way).

Incremental Design And Architecture

Be very cautious of using customer-centric stories without also using most of the XP development practices. Customer-centric stories depend on the ability to implement infrastructure incrementally with incremental design and architecture. Without this ability, you're likely to incur greater technical debt.

Sit Together

Physical index cards are only appropriate if the team sits together, or at least has a common area in which they congregate. Experienced distributed teams often keep physical index cards at the main site and copy the cards into the electronic system. This is an administrative headache, but for these teams, the benefits of physical cards make the added work worthwhile.

Some organizations are skittish about using informal planning tools. If important members of your organization require a formal Gantt chart, you may need to provide it. Your project manager can help you make this decision. As with a distributed team, you may find it valuable to use physical cards as well, then duplicate the information into the tool.


For teams that don't use stories, the main distinction between stories and the line items in most plans is that stories are customer-centric. If you can't use customer-centric stories for some reason, customers cannot participate effectively in the planning game. This will eliminate one of its primary benefits: the ability to create better plans by blending information from both customers and programmers. Unfortunately, no alternative practice will help.

Another distinctive feature of stories is the use of index cards. Physical cards offer many benefits over electronic tools, but you can still use an electronic tool if necessary. Some teams track their stories using spreadsheets and others use dedicated agile planning tools. None of these approaches, however, provide the benefits of physical index cards.

Further Reading

Agile Estimating and Planning, by [Cohn], discusses options for splitting stories in Chapter 12.

If you liked this entry, check out my best writing and presentations, and consider subscribing to updates by email or RSS.