Definition of Ready

Below you will find the high-level guidelines for stories to meet what we consider the definition of ready. This is what the VS team uses as a guideline to write their stories for our platforms.


As we dive into this document, it is equally important to know when to stop writing requirements. Reading the definitions below could send you down a deep rabbit hole to answer every single question possible - avoid this. Write the minimum amount to meet the definition below and let the team help you define this as you proceed.

The below document is in the order in which I would approach each step, but feel free to use your own order.

Clear and Concise Summary

Always start with a clear and concise summary of the story. Below I’ve outlined some good examples and some that could be improved.
The Good:
  1. Update the terms of service to include new wording provided by legal
  2. Allow users to filter the posts on their Homepage feed by “most likes”
  3. [Bug] “Upload” button on Homepage should have the same drop shadow as all other buttons
The Bad::
  1. Update TOS for Legal
  2. Add a new filter in Homepage feed
  3. Upload button shadow fix
The Ugly:
  1. Copy changes
  2. Homepage filter update
  3. Fix something
Keep in mind that a clear and concise summary does not excuse you from writing a proper description (if required).
For the templates that we use, this can be placed in the in the “Goal” section of Example Mapping for features/chores or the area above “Steps To Reproduce” on a bug ticket

Answer the Why

The main thing you should keep in mind when trying to write any story, is to answer the “why”. Always ask yourself, “Why are we building this feature” and then try to answer that question in your story.
Identifying the “why” ensures that we are moving towards a product focused engineering organization. It will also ensure that the person working on the ticket understands why they are doing this work and gives them the ability to pick up on something that is missing, make improvements/suggestions and be part of the whole as opposed to having a siloed understanding. So, always start with the “why”.
Answering the why can often be accompanied by defining your goal for the ticket.
When you answer the “why” you want to ensure that you have included the benefits or “what” you will achieve. A good example of this is the following:
  1. In our recent survey (Do you like dark mode - July 13th, 2020) we identified that 83% of all users surveyed would like to have the ability to switch to dark mode. This means that we have at least 3,547 users who are asking us for dark mode. Furthermore, in a test we conducted on, the majority of users immediately switched to using the dark mode theme.
User Stories

Often times, teams choose to write user stories in the the “As a user, I’d like to do something, so that I can get the following result” style. This style is quite popular and often used. A good example and a bad example are listed below.
Good User Story:
As a user, I’d like to have an “upload resume” button, so that I can upload my resume and apply for a job.
Bad User Story:
As a user, I’d like a system, so that I can update my job application. (vague and too large)
As a moderator I want to be able to update the system. (ambiguous)

Acceptance Criteria and Example Mapping

Before we even describe what this is, it is critical to state that the ENTIRE team is responsible for writing acceptance criteria and virtually anyone can write them. Do NOT depend solely on a product manager or scrum master to write these (they aren’t all knowing - contrary to popular belief).

Think of acceptance criteria as the “rules” of your story. Google defines this as “Pre-established standards or requirements a product or project must meet.” If you have great acceptance criteria in your issues, the entire team will have an easier time “accepting” the issue when it is completed - especially the Quality Assurance team!

Acceptance criteria needs to be clear and unambiguous to the team. Equally importantly, the acceptance criteria must be testable, if it is not, the issue will never be accepted/passed by the team.

Some users choose to write acceptance criteria as a rules checklist and this is also acceptable. This is often used when the story and scenarios are simple.

I’ve included an example of good acceptance criteria here in a scenario manner:

Given that I have navigated to the Homepage feed

When I select to sort my feed by likes in a descending order

Then my Homepage feed must be sorted by likes with the highest on top and the lowest at the bottom

The same acceptance criteria can be described as a rule:

Selecting to sort my Homepage feed by likes in a descending order, should reorder my feed by likes with the highest likes at the top and the lowest at the bottom (descending order)

Always start with the “Normal case”.

Expand to the “Negative case” for issues whenever possible. A negative case is the when an error would occur and how to handle the error. A good reference doc is here: Negative Test Cases

Consider “Edge case” for larger issues. An edge case is something that is not likely to happen in your given/described scenario. For example, if you are asking for someone to fill out a form and enter their name and edge case would be if the user entered special characters or an entire encyclopedia into the form field. It is important to think through these in most cases.

An example of bad acceptance criteria would be the following:
  1. I can do what the ticket says. (vague and ambiguous)
  2. The devs have built a spreadsheet that allows me to enter my values that will directly be reflected in the copy on the homepage header. (Solutioning)
    1. A better way to state this is: I have the ability to update the homepage header without requiring a code change or going through a release process.
Lastly, it is important to share this early and get feedback from Engineers and QA at the very least. This can be expanded further to include CM and other teams as needed. This should be done before the planning meeting.

If the acceptance criteria is "the rule", "example mapping" is the scenario that will describe that rule. Acceptance criteria and example mapping are often used together without distinguishing between the two. If you state a rule, you are using the more traditional approach for acceptance criteria, if you are using examples, it is example mapping. Both examples are above.


Your stories need to be complete before planning sessions. For example, designs should be completed and reviewed prior to planning sessions. If a story is missing designs, it does not meet the definition of ready. Several things could be dependencies, but designs are the most common. A spreadsheet with formulas, a document with the copy are some other examples of what could be categorized as a dependency to meet the definition of ready.
  • A rough estimation is a dependency for SP1 for proper prioritization.
  • Ticket priority at a Product level is a dependency for SP1 (though priority on some tickets might be adjusted after SP2).
  • Technical design is a dependency for the start of the sprint. It should be added during/after SP2 and before starting the ticket, or the engineering group can opt-out of tech design for a ticket in SP2 if they feel it’s not necessary.
  • For larger issues, walking the team through designs/mocks/requirements is a dependency for doing tech design and estimation in SP2. This should be done before or during SP1.
  • If there are dependencies between tickets or if a ticket contributes to an epic/initiative they should be linked or included.

Data Driven Decisions - Include Your Data

An important question to ask for each story you write is “does the data support your request”? If not, you need to rethink your proposition. If so, then include your data in your story, and let everyone see the data and more importantly, understand the data. It doesn’t end here though, the data should then drive your decisions and be factored into your definition of done.

The more data you have, the better it is for your case, but that doesn’t mean you should just dump data into your issue, link to the raw data, but always provide the curated data for easy review. A good example of this is when we saw the click rates on recommended reading go up significantly, it was a great measure for us to push it to more sites. Similar data applies to our Homepage 2.0.

When possible, we should include the following information.
  • If there’s external dates (legal, contractual, etc) they should be mentioned.
  • If there are known or estimated costs that we incur if we don’t complete this ticket it should be included.
  • If there are known or estimated business gains (could be financial or strategic) from completing a ticket then it should be included.
Do NOT Provide Solutions

It is often very easy for the Product team to propose solutions instead of outlining the problem. When you do this, people will immediately try to implement YOUR solution, even though there might be a better solution out there. They will do this because they do not understand the problem, you have not provided it for the team. This is something that the Engineering team should take care of. Be careful not to provide solutions.

Product goals and requirements for a ticket should not specify a specific implementation/solution - solutions should be picked as part of a conversation with the team. This could happen in advance of SP1, but otherwise solutioning happens (quickly) in SP1 as part of the ticket walkthrough.

Use The RACI

Chart available to VS employees only.


Every story should hopefully follow the I.N.V.E.S.T abbreviation. Click here for detailed explanations.
Your story should be:

  • Unrelated to other stories (if possible).
  • Not an explicit list of requests, but instead a negotiable list.
  • Should always add value.
  • Something that we can estimate with reasonable confidence.
  • Refer to “Vertical Slice” below.
  • We must be able to test it and pass the test.
Stories Should Be A Vertical Slice

If you’ve followed everything we’ve outlined so far, then you should be pretty close to a vertical slice for your story already. A vertical slice is basically a story that can stand on its own from start to finish or a complete and deliverable piece. Now, this does not mean that an entire feature is a vertical slice, it is important to keep your slices small. A good example of this is one that I always like to use “A button to upload my resume”.

In the example of “a button to upload my resume”, you could break it down into just adding the button to the UI. Essentially, this would be a button that does nothing and this would be an acceptable story from all of the criteria above, but it would not really represent a vertical slice of your application, because you would be missing some key pieces here. For example, did you include the JavaScript? Can I upload an actual file? Can I store my file somewhere? Your vertical slice means that your story covers everything from the User Interface all the way to the Database and everything in-between without being too large.

This concept can be very difficult to grasp and people often struggle with two questions, “Is it too big?” or “Is it too small?”.

If a ticket can be sliced vertically in terms of product functionality it should be done in advance of SP1 (what things a user will be able to do, iterations towards a nicer solution/experience).

If a ticket can be sliced vertically in terms of technical implementation it should be done at the time tech design happens (generally in SP2) or shortly thereafter (before the sprint starts).

A link with some great material.