agentleFS
robconeryrobconery/kolea/.claude/skills/user-stories/SKILL.md

user-stories

Skill7 starsChanged 3 months agoMITView on GitHub

Write, split, and refine agile/scrum user stories and acceptance criteria. Produces /docs/STORIES.md as the canonical backlog, formatted to feed directly into the bdd-specs skill (Story → Feature, Given/When/Then acceptance criteria → Scenario/Specification). Use this whenever the user wants to write a user story, capture requirements as stories, "groom" or "refine" a backlog, break an epic or feature into stories, split a story that is too big, write or tighten acceptance criteria, draft a Definition of Done, or turn a vague feature request or PRD into a structured backlog — even if they don't say the words "user story" or "scrum".

23 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use brainstorm-experiments-new, brainstorm-experiments-existing and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • skytiger6724Skill

    brainstorm-experiments-new

    Design lean startup experiments (pretotypes) for a new product. Creates XYZ hypotheses and suggests low-effort validation methods like landing pages, explainer videos, and pre-orders. Use when validating a new product idea, creating pretotypes, or testing market demand.

    Also in 9 projects that use this

  • skytiger6724Skill

    brainstorm-experiments-existing

    Design experiments to test assumptions for an existing product — prototypes, A/B tests, spikes, and other low-effort validation methods. Use when validating assumptions, testing feature ideas cheaply, or planning product experiments.

    Also in 7 projects that use this

  • 45ckSkill

    pestle-analysis

    Also in 7 projects that use this

  • About-IntelligenceSkill

    positioning-ideas

    Brainstorm product positioning ideas differentiated from competitors.

    Also in 7 projects that use this

  • launchapp-devSkill

    interview-script

    Create a structured user interview script with warm-up, core exploration, and wrap-up sections. Use when preparing for user research interviews to ensure consistent, insightful conversations.

    Also in 10 projects that use this

  • About-IntelligenceSkill

    product-name

    Brainstorm 5 unique, memorable product names with rationale aligned to brand values and target audience.

    Also in 7 projects that use this

  • +6 more from skytiger6724

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 2 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write acceptance criteria as Given/When/Then from the start.

    line 35
  2. Distinctive:

    What: do they want to do?

    line 47
  3. Very specific:

    Ask the smallest number of questions that unblock you.

    line 53
  4. Very specific:

    Use the canonical form. Read assets/STORIES.template.md for the exact file layout and copy its structure — it is what bdd-specs expects.

    line 59
  5. Very specific:

    Keep one outcome per Then.

    line 77
  6. Very specific:

    Before considering a story done, check it against INVEST and the smells list in references/invest-and-quality.md.

    line 84
  7. Distinctive:

    Too big (not Small): If you cannot enumerate its acceptance criteria, or it spans multiple roles/outcomes, split it — see the splitting …

    line 87
  8. Very specific:

    Not Testable: If you cannot phrase the acceptance criteria as Given/When/Then with observable outcomes, the story is underspecified.

    line 92
  9. Very specific:

    Always write or update /docs/STORIES.md.

    line 127

“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

User Stories

Turn product intent into a structured, testable backlog in /docs/STORIES.md. The output is the input to the bdd-specs skill, so the structure here is not cosmetic — it is a contract. Get the format right and stories flow into executable specs and then code with no manual reshaping.

The pipeline you sit in

product intent ──▶ [user-stories] ──▶ /docs/STORIES.md ──▶ [bdd-specs] ──▶ spec files ──▶ code

bdd-specs reads /docs/STORIES.md and /docs/PLAN.md and generates nested specs: Feature > Scenario > Specification, where each Scenario arranges its data once and every Specification makes exactly one assertion, happy paths first and exhaustively, sad paths in their own block.

So map deliberately:

Story artifactBecomes in bdd-specs
One storyOne Feature
One acceptance criterionOne Scenario
Given / When / Then stepsThe Scenario's arrange / act / assert
Each distinct ThenOne Specification (one assertion)
Happy-path criteriaListed first, exhaustively
Error / edge criteriaA separate "sad path" group

Write acceptance criteria as Given/When/Then from the start. That single habit is what makes the handoff clean.

Workflow

1. Establish context before writing

A story carries product knowledge the codebase does not. Do not invent the role, the goal, or the value. If the user hands you a vague feature ("add notifications"), interview rather than guess:

  • Who is this for? (the role — be specific: "billing admin", not "user")
  • What do they want to do?
  • Why — what outcome or pain does it address? A story whose "so that" is hollow ("...so that I can use the feature") is usually a task, not a story.
  • What does done look like? What must be observably true?
  • What is explicitly out of scope for this story?

Ask the smallest number of questions that unblock you. If the user says "just draft it and I'll correct it", do that — draft, mark assumptions with > ASSUMPTION: lines, and let them react. Reacting is faster than specifying.

2. Write the story

Use the canonical form. Read assets/STORIES.template.md for the exact file layout and copy its structure — it is what bdd-specs expects.

As a <specific role>,
I want <capability>,
so that <outcome / value>.

Then acceptance criteria, each as a self-contained scenario:

AC1 — <short name>
  Given <starting state>
  When  <action>
  Then  <single observable outcome>

Keep one outcome per Then. If you need "and also", that is a second criterion (it will become a second Specification downstream). Cover the happy path exhaustively first, then error and edge criteria under a clearly separated heading.

3. Quality-gate every story with INVEST

Before considering a story done, check it against INVEST and the smells list in references/invest-and-quality.md. The two failures worth catching every time:

  • Too big (not Small). If you cannot enumerate its acceptance criteria, or it spans multiple roles/outcomes, split it — see the splitting patterns in the reference. Prefer vertical slices (a thin end-to-end capability) over horizontal ones ("build the API", "build the UI"), because a vertical slice is independently valuable and testable.
  • Not Testable. If you cannot phrase the acceptance criteria as Given/When/Then with observable outcomes, the story is underspecified. That is a signal to go back to step 1, not to lower the bar.

4. Epics and decomposition

An epic is a container, not a big story. Represent it as a heading that groups its child stories. Break an epic down only as far as the next sprint needs — near-term stories fully fleshed with acceptance criteria, later ones left as one-line placeholders. Over-decomposing a backlog that will change is waste (YAGNI applies to backlogs too).

5. Definition of Ready / Definition of Done

These are team agreements, so confirm them with the user rather than asserting house rules. Capture them once at the top of STORIES.md (the template has a slot). Default starting points are in the reference file; offer them, don't impose them.

Scope boundaries

  • In scope: writing stories, splitting/refining them, acceptance criteria, epic decomposition, Definition of Ready/Done, turning a PRD or feature request into a backlog.
  • Out of scope, say so plainly: story-point estimation and sprint capacity planning are team rituals that depend on a specific team's history and velocity — a skill cannot do them credibly. Offer relative-size flags (S/M/L, or "this is too big, split it") instead of fabricated point numbers.
  • Hand off, don't overlap: generating the executable specs from these stories is bdd-specs's job. Architecture/implementation planning is the Plan agent's or /docs/PLAN.md's job. Produce the backlog and point at the next step; don't do their work here.

Output

Always write or update /docs/STORIES.md. If it does not exist, create it from assets/STORIES.template.md. If it exists, merge — preserve story IDs already in use (downstream specs may reference them) and append or amend rather than rewriting wholesale. After writing, tell the user how many stories/epics the file now holds and that it is ready for bdd-specs.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.