Documentation
Stepwise Poker for Jira: user guide
Everything the app does, in the order you will meet it: creating a session, voting live or async, the decks, writing the estimate to Jira, and the details admins ask about.
On this page
Getting started
Stepwise Poker for Jira is a Jira Cloud app. A Jira admin installs it from the Atlassian Marketplace and approves its five permissions (they are explained under Permissions).
Open Stepwise Poker
- Open the space you want to estimate in.
- Choose Stepwise Poker in the space navigation.
- The page has three tabs: Sessions (open and finished sessions), Insights (Premium) and Settings (space admins).
Create a session
- On Sessions, press New session.
- Give the session a name (optional, up to 80 characters), such as Sprint 24 planning.
- Choose the mode: Live or Async (see Live and async sessions).
- Choose the deck (see Decks).
- Choose where the work items come from:
- Active sprint
- Upcoming sprints
- Backlog: work items without a sprint
- JQL query: your own search
- Start the session. Your colleagues open Stepwise Poker in the same space and join it from the list of open sessions.
Every source is a JQL search that is limited to the space you are in: the app wraps your query in project = … AND (…) and drops any ORDER BY of your own. The work items are listed in rank order, and the search runs as you, so only work items you may see are found. A session holds up to 150 work items: if more match, the first 150 are taken and the screen tells you.
Quick estimate on a work item
Every work item also has a Poker estimate panel. Press Estimate this work item and a round starts for that work item alone. If a colleague presses it too, they join the same session.
Live and async sessions
Live sessions
In a live session the team looks at one work item at a time. The room shows the work item (key, title, type, status, priority, assignee, the start of the description and the current value of the estimate field), the deck, and who in the team has voted.
- The facilitator starts a round for a work item. Any work item that is still waiting can be taken next.
- Everyone picks a card. You see who has voted, never what, until the reveal.
- The facilitator presses Reveal cards. All cards and notes appear together, with the results below.
- If the team is far apart, Vote again starts a new round on the same work item.
- The facilitator presses Accept estimate (see Writing the estimate), then moves on. Skip leaves a work item out (its votes are deleted), and Finish session closes the session and keeps only the results.
What the reveal shows
- Average and median
- Calculated from the numeric cards. The ? card and the break card are not numbers and do not count.
- Spread
- The lowest and the highest card, and how many cards of the deck lie between them.
- Agreement
- The share of votes on the most common card.
- Consensus
- Shown when all votes sit on one card, or on two neighbouring cards.
- Suggested estimate
- The card nearest to the median. If two cards are equally near, the higher one is suggested.
Round timer
A timer from 15 seconds to 60 minutes can run with every round. When it reaches zero the screen says Time’s up. Nothing is revealed on its own: the facilitator decides what happens next. The length is set in Settings.
Async sessions
In an async session every work item is open at once, so people vote when it suits them.
- Each person picks a card for each work item and may add a note (up to 300 characters) with the reasoning.
- A work item is revealed when the number of people you expect has voted, when the due date comes (the end of the day you chose, up to 90 days ahead), or when the facilitator presses the button, whichever happens first.
- The due date is checked whenever somebody opens the session or votes, so a reveal for a due date is shown the next time someone looks.
- The facilitator accepts the final estimate of each work item, as in a live session.
Decks
| Deck | Cards |
|---|---|
| Fibonacci | 0, 1, 2, 3, 5, 8, 13, 21, 34 |
| Modified Fibonacci | 0, ½, 1, 2, 3, 5, 8, 13, 20, 40, 100 |
| Powers of 2 | 0 up to 64 |
| T-shirt sizes | XS (1), S (2), M (3), L (5), XL (8), XXL (13): each size counts as the number in brackets |
Every deck also has a ? card (not sure) and a break card. A deck is copied into the session when it starts, so changing the settings later does not change a session that is already running. With Premium you can add your own decks (see Premium features).
Writing the estimate
The estimate is never written on its own. When the facilitator presses Accept estimate:
- A card is selected, by default the suggested one. The facilitator can pick another card or type a number from 0 to 1000, with at most two decimals.
- The box Write <field> to the work item in Jira is on when the space settings name a field.
- The app saves the number to the work item as the facilitator, with the facilitator’s own Jira permissions.
Which field
A space admin chooses the field in Settings:
- A number field: Story point estimate and Story points are listed first.
- Original estimate: the time estimate of the work item. One point is saved as one hour.
- Do not write to Jira: the session only records the results.
Each accepted estimate has a status in the session summary: written, skipped (accepted without writing to Jira) or none (the space has no field chosen).
What the errors mean
- The field is not on this work item’s edit screen, or it only takes other values
- Jira refused the number. The field is not part of the screen for that work type, or it does not accept this value. The estimate is not accepted and nothing changed. Retry, choose another card, ask a Jira admin to add the field to the screen, or accept the estimate without writing to Jira.
- No permission, or the work item is hidden
- Jira checks the facilitator’s permissions, not the app’s. The facilitator needs permission to edit the work item.
- An estimate was accepted a moment ago
- Another person accepted this work item first. The room shows the accepted result.
- Voting is closed
- The cards were revealed before your vote arrived. A vote that arrived first is counted.
- Someone else changed the session at the same moment
- Two people pressed a button at once. Press it again.
When Jira refuses, the estimate is not accepted. The facilitator can retry, pick another card or accept without writing to Jira, in which case the summary records skipped.
Roles
- Facilitator
- The person who created the session. Starts rounds, reveals, starts a new round, accepts estimates, skips work items and finishes the session. The facilitator always votes too. A space admin can run a session that has no facilitator.
- Participant
- Votes, and counts in the average, median and agreement.
- Observer
- Watches the room and the results without voting. A person switches their own role between voter and observer in the room, and an observer does not count in the results.
A person who loses access to the space leaves the room. Jira permissions are checked again about every five minutes.
Settings
Space admins open the Settings tab of Stepwise Poker. The settings belong to the space, and a session takes a copy of them when it is created.
- Default deck for new sessions.
- Write accepted estimates to (the estimation field): a number field, Original estimate or none (see Which field).
- Round timer: the length of the timer in a round.
- Custom decks (Premium).
Privacy and data
- Sessions, votes, notes and settings are stored in Atlassian-hosted app storage (Forge storage), separately for your site. Nothing is written to work item properties.
- The only thing written to a work item is the accepted estimate, by the facilitator, when they choose to write it.
- Nothing is sent to any other server. There are no external services, no analytics and no AI.
- Names are not stored. The screen asks Jira for the names, as the person looking, and keeps them only in the open tab. In a session, a person is a random reference. Account IDs are kept in one table while at least one session of that person is open.
- While a session is open, votes and notes are kept. When a work item is finished, its votes and notes are deleted and only the numbers of its rounds remain.
- When a session is closed, all remaining votes and participants are deleted, and every person with no other open session is removed from the table. What stays: for each work item the number of votes, the lowest, the highest, the average, the median, the agreement and the final estimate, with its title.
- A session with no activity for 30 days is closed by a weekly job; its unfinished work items are marked as skipped. Summaries of closed sessions are kept for 13 months and then deleted.
- Once a week the app reports the account IDs it still holds to Atlassian’s personal data reporting, as Atlassian requires, and clears accounts that were closed.
- If you uninstall the app, Atlassian keeps app data for up to 28 days before it is removed.
- Data follows your Jira data residency.
Apart from the weekly clean-up, the app never acts on its own: it does not listen to events in your Jira, and every action runs as the person who pressed the button.
Permissions
When the app is installed, Jira asks the admin to approve five permissions:
| Permission | Why the app needs it |
|---|---|
read:jira-work | To find the work items of a sprint, the backlog or a query, to show a work item in the room, to ask Jira what the current person may do in the space, and to list number fields for the settings |
write:jira-work | To save the accepted estimate to the work item, as the facilitator. Nothing else is written |
read:jira-user | To show people’s names in the room. Names are shown, never stored |
storage:app | To keep sessions, votes, notes, settings and the table of people in Atlassian-hosted app storage |
report:personal-data | To report the account IDs held while sessions are open to Atlassian’s personal data reporting |
The list has no Jira Software permissions: the sprint and backlog sources are JQL searches. The app uses no external addresses.
Limits
| Item | Limit |
|---|---|
| Work items per session | 150 |
| People per session | 50 |
| Open sessions per space | 25 |
| Session name | 80 characters |
| Note with a vote | 300 characters |
| Round timer | 15 seconds to 60 minutes |
| Async due date | up to 90 days ahead |
| Final estimate | a card of the deck, or a number from 0 to 1000 with up to two decimals |
| Custom decks (Premium) | 10 decks, 20 cards each |
| Idle sessions | closed after 30 days without activity |
| Closed session summaries | kept for 13 months |
Troubleshooting
- The estimate was not written to the work item
- Read the message: it is Jira’s own reason. Check the Estimation field in Settings, check that the field is on the edit screen of that work type, and that the facilitator may edit the work item. Then retry, pick another card, or accept the estimate without writing to Jira and set the field by hand. See What the errors mean.
- A work item is missing from the sprint or backlog
- Each source is a search:
sprint in openSprints()for the active sprint,sprint in futureSprints()for upcoming sprints andsprint is EMPTYfor the backlog, always inside your space and as you. Run the same search in Jira’s work item search to see what it finds. Work items that you cannot see are not found, and work items of other spaces are never added. A session holds the first 150 matches. - I cannot see a session
- Sessions belong to a space: open Stepwise Poker in the same space as the person who started it, and look in the list of open sessions. You need access to the space. If your site’s license for the app is not active, sessions open for viewing only until it is. A closed session shows its results only.
- Someone is missing from the room
- A person appears when they open the session. Anyone who closed the tab can open the session again. A person who lost access to the space leaves the room within about five minutes, and an observer is not counted among the voters.
- The room looks out of date
- The screen refreshes by itself. If the connection drops it shows that it is offline and tries again. Reload the page to catch up at once.
- The reveal in an async session came late
- The due date is checked when someone opens the session or votes. The first person who looks after the due date sees the reveal.
Support
Most questions are answered here. For everything else, write to stepwise@pr.tools and start with the product: Stepwise Poker for Jira. We aim to reply within 2 business days. Please include what you were doing, the exact text of any message, and where it happened. We cannot see your Jira site, so hide anything confidential in screenshots and never send passwords or API tokens. More on the support page.