User Story (Agile)

You can learn how to fill in the details of a user story work item in this topic. For information about what user stories are and how they are used in agile processes, see Creating a Great Product Backlog. For information about how to create a work item for a user story, see Work Items and Workflow (Agile).

In this topic

Related topics

Defining a User Story Adding and Linking Tasks to a User Story Adding and Linking Test Cases to a User Story Adding an Issue to a User Story Adding Details, Attachments, or Hyperlinks to a User Storys Resolving and Closing a User Story

Agile Processes Creating a Great Product Backlog Scrum Agile Workbooks Product Planning Workbook Iteration Backlog Workbook Agile Reports (Reporting Services) Stories Overview Report (Agile) Stories Progress Report (Agile) Field Reference Assignments and Workflow (Agile) Areas and Iterations Planning, Ranking, and Priorities Titles, IDs, Descriptions, and History (Agile) Linking Work Items (Agile) Attachments

Required Permissions

To view a user story, you must be a member of the Readers group or your View work items in this node must be set to Allow. To create or modify a user story, you must be a member of the Contributors group or your Edit work items in this node permissions must be set to Allow. For more information, see Managing Permissions.

Defining a User Story

A user story communicates functionality that is of value to the end user of the product or system. Each user story should simply state what a user wants to do with a feature of the software and describe it from the user's perspective. When you write user stories, you should focus on who the feature is for, what they want to accomplish, and why. You should avoid descriptions that specify how the feature should be developed.

The work item form for a user story stores data in the fields and tabs that the following illustration shows:

When you define a user story, you must define the Title in the top section of the work item form. You can leave all other fields blank or accept their default values.

To define a user story

1. In the top section of the work item form for the user story, specify one or more of the following types of information:

   • In Title (Required), type a short description.

     Good story titles reflect the value to the customer or functionality that needs to be implemented.

   • In the Assigned To list, click the name of the team member who owns the user story.

     Note

     You can assign work items only to members of the Contributors group.

     If you leave the story unassigned, it is automatically assigned to you.

   • In the Rank box, type a number that indicates the relative importance of the story compared to the other stories in the product backlog.

   • In the Story Points box, type a number that specifies a subjective rating for the amount of work that will be required to complete a user story.

     If you specify more points, you indicate that more work will be required.

   • In the Priority list, click the level of importance for the user story on a scale of 1 (most important) to 4 (least important).

   • In the Area and Iteration lists, click the appropriate area and iteration or leave these fields blank to be assigned later during a planning meeting.

     Note

     The project administrator for each team project defines area and iteration paths for that project so that the team can track progress by those designations. For more information, see Create and Modify Areas and Iterations.

2. On the Details tab, specify the one or more of the following types of information:

   • In the Description with Acceptance Criteria box, provide as much detail as you want to describe not only the user story but also the criteria that you will use to verify whether the user story has been fulfilled.

     Your team will use this information to create work items for tasks and test cases. For more information, see Task (Agile) and Test Case (Agile).

   • In the History box, add comments that you want to capture as part of the historical record.

     Every time that a team member updates the work item, its history shows the date of the change, the team member who made the change, and the fields that changed.

3. Link the user story to other work items, such as tasks, test cases, bugs, and issues.

   For more information, see the following sections later in this topic:

   • Adding and Linking Tasks to a User Story

   • Adding and Linking Test Cases to a User Story

   • Adding a Bug to a User Story

   • Adding an Issue to a User Story

   • Adding Details, Attachments, or Hyperlinks to a User Story

4. Click Save Work Item.

Note

After you save the user story, the identifier appears in the title under the work item toolbar.

Adding and Linking Tasks to a User Story

You add tasks to a user story to track the progress of work that has occurred to complete the user story.

Note

The Stories Overview and Stories Progress reports require that you create links between user stories and tasks and between user stories and test cases. For more information, see Stories Overview Report (Agile) and Stories Progress Report (Agile).

To create a task that is linked to a user story

1. On the Implementation tab, click New.

   The Add new Linked Work Item dialog box opens.

   

2. In the Link Type list, leave the default option, Child.

3. In the Work Item Type list, click Task.

4. In Title, type a name that identifies the area of work to be performed as specifically as possible.

5. (Optional) In Comment, type additional information.

6. Click OK.

   A work item form for a task opens with the information that you have provided.

7. Specify the remaining fields as described in Task (Agile), and then click Save Work Item.

To link several existing tasks to a user story

1. On the Implementation tab, click Link to.

   The Add Link to User Story dialog box opens.

2. In the Link Type list, leave the default option, Child.

3. Click Browse.

   The Choose Linked Work Items dialog box appears.

   

4. Type the items in Work item IDs, or browse for the items to which you want to link. You can also run the My Tasks team query to locate the tasks to which you want to link. Select the check box next to each task that you want to link to the user story. For more information, see Find Work Items to Link or Import.

5. (Optional) Type a description for the tasks to which you are linking.

6. Click OK, and then click Save Work Item.

   Note

   Both the user story and tasks that you linked are updated. A parent link to the user story is created for each task that you added.

Adding and Linking Test Cases to a User Story

As part of planning, you create test cases and link them to user stories. The recommended client for creating test suites and test cases is Microsoft Test Manager. From this client, you can also link to a user story as described in How to: View Requirements or User Stories Using Microsoft Test Manager.

To add a new test case to a user story

1. On the Test Cases tab, click New.

   The Add new Linked Work Item dialog box opens.

2. In the Link Type list, leave the default option, Tested By.

3. In the Work Item Type list, leave the default option, Test Case.

4. In Title, type a descriptive name that defines the area to be tested.

5. (Optional) In Comment, type additional information.

6. Click OK.

   A work item form for a test case opens with the information that you have provided.

7. Specify the remaining fields as described in Test Case (Agile), and then click Save Work Item.

To add existing test cases to a user story

1. On the Test Cases tab, click Link to.

   The Add Link to User Story dialog box opens.

2. In the Link Type list, leave the default option. Tested By.

3. In Work item IDs, type the IDs of the test cases that you want to link, or browse for them.

   You can run the My Test Cases team query to locate the test cases that you want to add, and then select the check box next to each test case to which you want to link. For more information, see Find Work Items to Link or Import.

4. (Optional) Type a description for the test cases to which you are linking.

5. Click OK, and click Save Work Item.

   Note

   Both the user story and test cases to which you linked are updated. A Tests link to the user story is created for each test case that you added.

Adding an Issue to a User Story

You can create a work item for an issue and link it to the user story from the All Links tab. By defining the issue and linking it to the user story, you can better track the quality and completion of the user story.

To create an issue and link it to a user story

1. On the All Links tab, click New.

   The Add new Linked Work Item dialog box opens.

2. In the Link Type list, click Related.

3. In the Work Item Type list, click Issue.

4. In Title, type a name that identifies the blocking issue as specifically as possible.

5. (Optional) In Comment, type additional information.

6. Click OK.

   A work item form for an issue opens with the information that you have provided.

7. Define the remaining fields as described in Issue (Agile), and then click Save Work Item.

Adding Details, Files, and Hyperlinks to User Stories

You can add details to user stories in the following ways:

• Type information in the Description or History field.

• Attach a file.

  For example, you can attach an e-mail thread, a document, an image, a log file, or another type of file.

• Add a hyperlink to Web site or to a file that is stored on a server or a Web site.

To add details to a user story

1. On the Details tab, type information in the Description field.

2. (Optional) Type information in the History field.

   You can format information to provide emphasis or capture a bulleted list. For more information, see Titles, IDs, Descriptions, and History (Agile).

3. Click Save Work Item.

To add an attachment to a user story

1. On the Attachments tab, perform one of the following actions:

   • Drag a file into the attachment area.

   • Click or press CTRL-V to paste a file that you have copied.

   • Click Add, and then click Browse. In the Attachment dialog box, type or browse to the name of the file that you want to attach.

     (Optional) In the Comment box, type more information about the attachment. To return to the Attachments tab, click OK.

2. Click Save Work Item.

To add a hyperlink to a user story

1. On the All Links tab, click Link to.

   

2. In the Link Type list, click Hyperlink.

3. In the Address box, type the address of the target of the link.

4. If the target is a Web site, type the URL, or copy it from your Internet browser and paste the URL into the Address box. If the target is a server location, type the address in the form of a UNC name.

5. (Optional) In the Comment box, type more information about the hyperlink.

6. Click OK, and then click Save Work Item.

Resolving and Closing a User Story

You can use the Active, Resolved, and Closed states to track the progress of user stories. When you have written the code to implement a user story and all unit tests have passed, you change the State of the user story to Resolved. After all tasks are completed and the user story passed all acceptance tests, you change its State to Closed. Any team member can change the state of a user story.

For more information about the data fields that you can use to track work item states, see Assignments and Workflow (Agile).

To resolve or close an active user story

1. Open the user story.

2. In the State list, click Resolved or Closed.

   • If you change the state from Active to Resolved, the Reason field automatically changes to Code complete and unit tests pass.

   • If you change the state from Resolved to Closed, the Reason field changes to Acceptance tests pass.

   • If you change the state from Active to Closed, you should click the Reason that matches your intent, as Active to Closedlater in this topic.

3. Click Save Work Item.

Typical workflow progression: A customer representative creates a user story in the Active state with the default reason, New. A team member changes the state of the user story from Active to Resolved when it is code complete and unit tests have passed A team member changes the state from Resolved to Closed when the test cases that were defined for the user story have passed Atypical transitions: A customer representative determines that the user story is not relevant or out of scope and changes the state from Active to Closed An acceptance test for the user story fails. Therefore, a team member changes the state from Resolved to Active A customer representative determines that the user story was closed in error or is now in scope and changes the state from Closed to Active

User Story State Diagram

Active (New)

The following data fields are automatically captured when a team member creates a user story:

• Created By: Name of the team member who created the work item.

• Created Date: Date and time when the work item was created, as recorded by the server clock.

From Active to Resolved

You can resolve an active user story for the following reason:

Reason	When to use	Additional actions to take
Code complete and unit tests pass	When the code to implement a user story is checked in and all unit tests have passed.	Assign the user story to the team member who will test it.

The following data fields are captured when a team member resolves an active user story:

• Resolved By: Name of the team member who resolved the work item.

• Resolved Date: Date and time when the work item was resolved, as recorded by the server clock.

• State Change Date: Date and time when the state of the work item was changed.

From Active to Closed

You can close an active user story because of one of the following reasons:

Reason	When to use	Additional actions to take
Rejected (default)	You determine that the user story represents a feature or requirement that does not support a business requirement, scenario, or value proposition.	None.
Abandoned	The user story is no longer considered necessary to implement.	None.
Out of Scope	The team has insufficient resources to implement the user story for the current iteration. A user story might be identified as out of scope because the team has insufficient time or because blocking issues were discovered.	Update the Iteration field to specify in which iteration the scenario will be implemented. If the scenario is deferred to the next release of the software, leave the Iteration field blank, but describe in detail why the scenario was deferred and when it should be implemented.

The following data fields are captured when you close an active user story:

• Closed By: Name of the team member who closed the work item.

• Closed Date: Date and time when the work item was closed, as recorded by the server clock.

• State Change Date: Date and time when the state of the work item was changed.

Resolved

When a user story is implemented in code, the lead developer sets the state to Resolved and assigns the story to a tester so that testing can start.

From Resolved to Closed

You can close a resolved user story for the following reason:

Reason	When to use	Additional actions to take
Acceptance tests pass	All test cases that are associated with the user story have passed.	Assign the user story to the product owner.

The following data fields are automatically captured when a team member closes a resolved user story:

• Closed By: Name of the team member who closed the work item.

• Closed Date: Date and time when the work item was closed, as recorded by the server clock.

• State Change Date: Date and time when the state of the work item was changed.

From Resolved to Active

You can reactivate a resolved user story for the following reason:

Reason	When to use	Additional actions to take
Acceptance tests fail	When at least one of the user story's tests failed.	Assign the user story to the lead developer. Also, the tester should create bugs for the test failures.

The following data is automatically captured when you reactivate a resolved user story:

• Activated By: Name of the team member who reactivated the work item.

• Activated Date: Date and time when the work item was reactivated, as recorded by the server clock.

• State Change Date: Date and time when the state of the work item was changed.

Closed

A closed user story can be reactivated if it comes back into scope. Usually a business analyst or program manager reactivates a closed user story.

From Closed to Active

You can reactivate a closed user story for the following reasons:

Reason	When to use	Additional actions to take
Reintroduced in Scope	Resources are available to implement the user story.	Make sure that the implementation tasks, test cases, and details that have been defined for the user story are complete and up to date.
Closed in error	A user story was closed before all associated tasks, test cases, or bugs were closed.	Make sure that the implementation tasks, test cases, and details for the user story are well defined and sufficient to support its development.

The following data is automatically captured when you reactivate a closed user story:

• Activated By: Name of the team member who reactivated the work item.

• Activated Date: Date and time when the work item was reactivated, as recorded by the server clock.

• State Change Date: Date and time when the state of the work item was changed.

See Also

Concepts

Product Planning Workbook

Other Resources

MSF for Agile Software Development v5.0

Plan the Sprint

Work Items and Workflow (Agile)