# User Story

User stories should include a descriptive title, a well-defined description, and acceptance criteria (frequently referred to as AC) and any supporting documentation that describes the feature in as much detail as possible (wireframes, screenshots, etc)

It is absolutely essential that all tasks, including user stories, are well-defined and understood by all developers before any work is actually started.

Frontend and backend work is typically completed asynchronously, so any misunderstanding or miscommunication in the story development process can lead to bugs, updates, or costly rewrites.

We place extra strong emphasis on defining API contracts before any frontend or backend work is started in order to avoid these issues.

# Sample User Stories

Title: As a user I can "View application roles"

Description:
  When a user clicks on an application in the application list page, they are taken to a page that lists the application
  detail. Roles for the application are listed in a table on this page.

Acceptance Criteria:
  - I can view a "loading skeleton" while roles are loading
  - I can view the following role fields - Name, Description, Created By, Created On
  - I can use pagination to navigate between pages
  - I can change the number of records I see on a single page

In this sample story, notice that there is no definition of other features that might be on the page in which roles are viewed. These features may be something like "As a user I can create a new role", "As a user I can delete a role", "As a user I can update a role", etc. These features are distinct from the current feature "As a user I can view roles" and should be encapsulated in other user stories that are all nested under an epic that might be named "Role management".

Title: As a user I can "Add an application role"

Description:
  When a user clicks a button on the application list page, a side sheet opens to a form which allows them to create a
  new role for the application. This form should also allow the user to add actions to the role.

Acceptance Criteria:
  - I can see and select a button on the Application Detail page which opens a side-sheet for adding a role - If I don't
    have the right to add a role, the button will not be visible
  - I can enter in my new role's name and description on the side sheet
  - I can assign application actions to the role in the side sheet using a searchable checkbox list - I can search the
    list of actions by name and read their descriptions before selecting each one - I can add and remove each item by
    selecting a checkbox - Items that are selected will be moved to the top of the list so they are easily removed
  - When I submit the click submit, the role is immediately added to the grid of roles on the Application Detail page
  - I can cancel the addition of a new role by clicking on a cancel button on the side-sheet - The application will stop
    and warn me after selecting cancel if any data has been entered into the form so I may reconsider

To support these stories, we also need to create backend tasks that define the API contracts the UI will interact with to implement a given story or feature. The examples on the API endpoint task page correspond to the two story tickets here.