User Guide

    Everything you need to ship great stories

    A practical walkthrough of every feature — from drafting your first story to exporting Azure-DevOps-ready output and collaborating with your team.

    1. Getting Started

    User Story Composer turns a short description into a fully-structured user story — title, As-a/I-want/So-that, business goal, context, expected outcome, Gherkin acceptance criteria, edge cases, and INVEST quality checks — ready to paste into Azure DevOps or Jira.

    1. — no credit card required.
    2. Open the app and you'll land on the Generator.
    3. Free plan includes a small monthly allowance. Upgrade or start a 14-day trial of Individual or Team for unlimited generations and refinement.

    2. Generator Mode

    The Generator drafts a brand-new story from a persona and a short description. Three ingredients matter:

    • Persona — pick from the curated list (User, Admin, Front Office User, RSM, etc.), or choose Other (specify)… to type your own role (e.g. Underwriting Analyst, Claims Adjuster) when none of the curated options fit. Custom personas are passed through verbatim; the AI may flag unusual ones as an ambiguity for you to confirm.
    • Industry (optional) — adds domain context so the Smart Drafter uses the right vocabulary (e.g. Insurance, Banking).
    • Description — one or two sentences describing the outcome you want the user to achieve.

    Examples

    "Allow back-office agents to bulk-reassign open claims to a colleague when going on leave, with an audit trail."
    "Build a button that calls the reassign endpoint and updates the table." (too technical, no user outcome)

    Clear vs Generate. Once a story is on screen the Generate button is disabled to prevent accidental overwrites — click Clear first to start fresh.

    3. Acceptance Criteria Format

    Choose how acceptance criteria should be written before you generate. The selector lives in the Input Panel, just under the Brief Description field.

    • Given / When / Then (default) — classic Gherkin steps. Best for QA hand-off and BDD tooling.
    • Grouped Bullets — themed groups (e.g. "Trigger Conditions") with a short intro and 2–5 sub-bullets each. Best for lightweight backlogs and stakeholder reviews.

    Your choice is remembered between sessions, so once you've picked your team's preferred style you won't have to re-select it.

    The format is locked once the story is generated — there's no in-place toggle on the output. To switch, click Clear, change the format, and regenerate.

    4. Validator Mode

    Already have a story written somewhere else? Switch to Validator, paste it in, and we'll score it against INVEST criteria, flag ambiguities, and suggest acceptance criteria you may be missing.

    Like Generate, the Validate button is disabled while a story is loaded — click Clear to validate a new one.

    5. Refining Stories

    Refinement (paid plans) lets you iterate on the current story without losing context. Type a short instruction and Smart Refine updates only what's needed.

    Good refinement prompts

    "Add an acceptance criterion for the screen-reader experience."
    "Tighten the So-that to focus on regulatory compliance."
    "Add an edge case for when the customer is already deceased."

    6. Tasks Panel

    Once a story is finalised, the Tasks panel can draft a list of actionable tasks (analysis, design, build, test, docs). Edit any task inline, reorder, or remove what you don't need, then export the lot to your tracker.

    7. Process Diagram

    Every generated story has a collapsible Process Diagram panel in the output (closed by default). Open it and click Generate Diagram to produce a Mermaid flowchart TD derived from the story's actor, trigger, acceptance-criteria steps, decision points, and outcomes.

    Three actions are available:

    • Copy Mermaid — paste into Confluence, Notion, Azure DevOps wiki or Jira (all support Mermaid natively).
    • Download .svg — embed as an image anywhere.
    • Regenerate — re-run if the story has changed.

    The diagram honors your language selection, so node labels match the language you chose for the story. It is session-only — diagrams are not saved with the story, so copy the Mermaid source or download the SVG if you want to keep it.

    8. Saving & Library

    Hit Save to store the current story in your Library. Saving again on the same story updates the existing row — it does not create a duplicate, even after refinement.

    Open any saved story from the Library panel to load it back into the workspace. Team members can see stories saved against the team account.

    9. Exporting

    Each story can be copied or downloaded in several formats:

    • Azure DevOps — markdown ready to paste into a Work Item description.
    • Jira — wiki-markup formatted for Jira Cloud or Server.
    • Plain Markdown — universal fallback.

    Tasks export separately as a checklist or CSV.

    10. Translating Stories & Tasks

    Need the story or task list in another language? Click Translate… on the story output (or on the Tasks panel) to open the translation dialog. Pick a target language and you'll get a side-by-side translated view.

    • Copy the translated markdown to your clipboard.
    • Download it as a .md file.

    Translation is one-shot and not persisted — the original English story remains the source of truth in your Library. Re-open the dialog any time to translate again or to a different language.

    Note: only the generated content is translated. The app's UI stays in English.

    11. Plans & Limits

    • Free — limited monthly generations, no refinement.
    • Individual — unlimited generations, refinement, full export.
    • Team — everything in Individual, plus shared library and per-seat billing.

    Manage your plan from or compare plans on the .

    12. Team Collaboration

    Team plan owners can invite members from . Two roles exist:

    • Admin — manage members, billing, and the team library.
    • Member — generate, refine, and contribute to the shared library.

    Stories saved by any member are visible to the whole team.

    13. FAQ & Troubleshooting

    "Generate / Validate is disabled"

    A story is already loaded. Click Clear first, then generate or validate again.

    "Can I change AC format after generating?"

    No — the format (Given/When/Then or Grouped Bullets) is locked at generation time. Click Clear, switch the toggle in the Input Panel, then regenerate.

    "Where does the diagram go when I close the app?"

    Diagrams are session-only and aren't saved with the story. Use Copy Mermaid or Download .svg to keep a copy before you leave the page.

    "Translation looks off in places"

    Re-run the translation with a more specific target locale, or copy the translated markdown into your editor and tweak the bits you don't like — the original English story stays untouched.

    "Trial expired" or "Usage limit reached"

    Upgrade from to keep going. Usage resets monthly on the free plan.

    "The output mentions tech I didn't ask for"

    Try removing technical wording from your description and re-generating, or use Refine: "Remove implementation detail and keep it outcome-focused."