Using StoryCraft

Write, refine and split issues

Every action opens a dialog with a preview. You decide what is saved to Jira.

Apply Team Template

Turns rough notes in the description into a structured issue that follows the template for its issue type. StoryCraft also uses the example issue, the Project Context and the glossary.

  1. 1

    Save a few lines of notes in the issue description.

  2. 2

    In the StoryCraft panel, click Improve Description, then Apply Team Template. The panel shows which template issue it will use, or Set a team template if there is none.

  3. 3

    Review the result. Result shows exactly what will be saved; Diff compares it with the current description.

  4. 4

    Adjust it with an instruction under Refine further, or with Edit text. Undo last change steps back one refinement.

  5. 5

    Click Apply Changes to save the description, or Close and confirm Discard & Close to leave it unchanged.

The Diff view of Apply Team Template: the original bullet points in red, and the new User Story and Acceptance Criteria sections in green
The Diff view: removed lines in red, added lines in green. The same notes now follow the Simple User Story template.

Add a description first

Apply Team Template and Refine Description need a few words in the saved description. Rough notes are enough.

Refine Description

Changes an existing description with a plain-language instruction. StoryCraft marks it as Suggested when the description already has headings.

  1. 1

    Click Improve Description, then Refine Description.

  2. 2

    Type what should change, for example "Add 2 edge cases for payment timeouts", and click Generate Preview.

The Refine Description dialog with the instruction Add an edge case for a user who requests several reset links in a row, the Generate Preview button and the current description
Describe the change you want. The current description is shown below for reference.
  1. 3

    Review the Diff. Refine again as often as you like; each instruction is listed so you can see what was asked.

  2. 4

    Click Apply Changes. Reject / Revert drops all staged changes and starts again from the current description.

The Diff view with one new acceptance criterion highlighted in green and the rest of the description unchanged
Only the new acceptance criterion is highlighted; the rest of the description is unchanged.
  • Edit text (in the Result view) lets you change the proposal yourself. Use # for headings, - for bullets and [ ] for checklists. Edited text keeps headings, bullets and checklists, but not bold, links or other rich formatting.
  • If someone edits the description in Jira while you review, StoryCraft applies your version and tells you that it overwrote their change.

Clarify: Grill me and Ask a question

Clarify works on any issue, with or without a description. It has two modes.

Grill me

A short interview that fills the gaps in the issue, one question at a time. The questions depend on the issue type:

Stories and other types

Product owner

User value, scope, acceptance criteria and edge cases. Score: readiness for development.

Bugs

QA lead

Steps to reproduce, expected vs. actual behavior, environment and impact. Score: ready to fix.

Epics

Product manager

Goal, target users, success metrics, scope, first release and risks. Score: ready to break down.

  1. 1

    Click Clarify, keep Grill me selected and click Start grilling.

  2. 2

    Accept the suggested answer, pick an alternative or write your own, then click Answer & continue. Skip moves on without an answer.

A Grill me question about the scope of a password reset story, with a readiness score of 65 percent, the reason for the question, a suggested answer and two alternatives
Each question says why it matters and comes with a suggested answer and alternatives. The bar shows the readiness score.
  1. 3

    After up to eight questions, or when you click That's enough, wrap up, the interview ends.

  2. 4

    Apply to description works the answers into the right sections and opens the diff for review. Post Q&A as comment adds the questions and answers to the issue as a comment.

Grilling complete with one answered question, an Apply to description button, a Post Q&A as comment button, and the list of answers
When the interview ends, apply the answers to the description or post them as a comment.

Ask a question

Ask anything about the issue, or click a suggested question for its type, such as Run an INVEST check for stories or Are reproduction steps complete? for bugs. The answer lists Gaps and Recommendations. When it suggests changes, Convert Feedback to Refinement opens Refine Description with a matching instruction.

The answer to an INVEST check listing gaps and recommendations, with a Convert Feedback to Refinement button
An INVEST check on a story. Convert Feedback to Refinement turns the recommendations into a refinement you can review.

Break into Stories

On issues of type Epic, the panel has a Break into Stories button. StoryCraft proposes thin, vertically sliced stories that each deliver value on their own.

The StoryCraft panel on an epic with the buttons Improve Description, Clarify, Break into Stories and Configure Templates
  1. 1

    Click Break into Stories. Optionally add guidance, such as "Split by user role" or "MVP first, admin features later".

  2. 2

    Click Propose stories. StoryCraft proposes up to ten stories, written in your Story template. If the epic already has child issues, it skips the work they cover.

Break into Stories with the reasoning behind the split, a note that descriptions follow the team's story template JIR-93, and the first proposed story, plus a Create 5 stories button
StoryCraft explains how it split the epic and which story template the descriptions follow.
  1. 3

    Edit the summary and description of each story, or untick Include for the ones you don't need. Propose again starts a new proposal.

  2. 4

    Click Create stories. They are created as children of the epic, with links to open each one.

A proposed story with an Include checkbox, an editable summary and a description with User Story and Acceptance Criteria headings
Every proposed story can be edited or unticked before it is created.

Grill the epic first

Stories are only as good as the epic's goal and scope. If the epic has no description, StoryCraft offers Grill this epic before proposing stories.

Best practices

  • Set a template for every issue type your team uses. Applying a template only works as well as the template itself.
  • Write a short Project Context and run a glossary scan once. Both improve every feature at no extra effort.
  • Use Grill me before refinement meetings: answering eight questions takes a few minutes and surfaces the gaps early.
  • Refine in small steps. "Add an edge case for expired links" gives a cleaner diff than "improve the acceptance criteria".
  • Read the diff before you click Apply Changes. StoryCraft never saves without you, but it relies on you to check the content.