Help

How to use Speclr

Refinement: turn stories into Story Artifacts

How to pick a story in Refinement, work on its Story Artifact with Speclr or by hand, read its quality assessment, and come back to it later.

Updated

What a story needs before you can finish it

  • Business RulesAt least one rule, written for this story or linked from elsewhere in the project.
  • A scenarioAt least one Gherkin scenario in Scenarios / Gherkin.
  • The rest sharpens itActors, Non-Functional Requirements, Data Fields and Boundaries are optional. The quality assessment checks them too.
  1. Pick a story from the list

    Refinement opens on your stories, grouped by milestone. Each row shows the story number, its title and a status: "In progress", "Not started" or "Finished". The card at the top suggests where to go on, "Continue where you left off" or "Start with the next story". Choose "Open story" there, or click any row.

    Milestones after the one you are working on show fewer stories, or only their header and progress; "Show N stories" or "Show N more" opens them. Rows can carry pills:

    • "Quality N": the score of the story’s last quality assessment.
    • "N marked": elements of the story are marked for review.
    • "N of M ready": where the team stands on the story.
    • "Removed from the map": a committed version of the User Story Map dropped it. The story stays in the list.
  2. Choose how to work on it

    The first time you open a story, Speclr reads its context and tells you what it found. Then it offers "Interactive Mode", "Pre Fill Mode" and "Auto Mode", as in the other phases. See Choose how to work.

    Sessions belong to a story: one running on this story does not stop anyone starting one on another.

  3. Read the Story Artifact

    The artifact has six sections: Business Rules, Scenarios / Gherkin, Actors, Non-Functional Requirements, Data Fields and Boundaries (In scope / Out of scope). The first two carry a "Required" pill. An empty section reads "Not yet specified."

    Once Speclr has assessed the story, the dot before each heading shows whether the section is complete, needs detail or is missing. Click the "Quality" pill in the header for the comment and the weak and missing sections.

  4. Change it yourself or tell Speclr

    Click a section to edit it yourself, row by row: see Edit artifacts yourself. Or point at a section and tell Speclr what to change, see Tell Speclr what to change.

    A section a team member is editing shows "editing…" and stays closed to you. While Speclr writes, the artifact is closed to edits.

    On the Professional and Business plans, Speclr may point out a potential risk in the story. A scenario or Non-Functional Requirement added against a risk says "Mitigates R-001 · …". See Risks.

  5. Finish the story

    When the required sections are in, choose "Finish this story…" below the conversation. See Finish a story.

Shared domain knowledge

Business rules, actors and data fields belong to the project, not to one story. A story links them, so a rule another story or an earlier phase established reads exactly like one written here. Terms from the project glossary are highlighted; point at one for its meaning. See Context.

Conflicts in the artifact

  • A red warning icon marks an entry that contradicts another one. Point at it to see which.
  • Amber arrows mark an entry that replaced an earlier one.

The artifact only shows the state. Open conflicts are listed in Context.

Pause and come back

"Close story" (the × at the top right) takes you back to the list. Content and conversation stay, and the story opens where you left it.

Closing does not end a running session. "End session" in the chat input does; everything captured so far is kept.