user-story-format
Reference only — the single definition of this project's user-story body (story, Gherkin ACs, Missing Information, DoD) and its AC/scenario rules. Read by user-story-enhancer (WAY 6) and benchmark-gap-story-writer (WAY 8) so stories they write stay identical in shape and WAY 6 can re-score WAY 8's output. Not a workflow on its own.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 5
- Forks
- 4
01 前言 Front Matter
- name
- user-story-format
- description
- Reference only — the single definition of this project's user-story body (story, Gherkin ACs, Missing Information, DoD) and its AC/scenario rules. Read by user-story-enhancer (WAY 6) and benchmark-gap-story-writer (WAY 8) so stories they write stay identical in shape and WAY 6 can re-score WAY 8's output. Not a workflow on its own.
03 SKILL.md 正文
user-story-format
Agents that write user stories Read this file and follow it exactly. When
the format changes, change it here only.
Story body
## User Story
As a <actor>, I want <goal> so that <business value>.
**Constraints:**
- <constraint>
- ...
---
## Acceptance Criteria
| # | Title | Priority |
|---|-------|----------|
| AC-01 | <title> | `must` |
| ... | | |
<details>
<summary>View full Gherkin scenarios</summary>
**AC-01 — <title>** `must`
- **Given** <precondition>
- **When** <action>
- **Then** <observable, assertable outcome>
...
</details>
---
## Missing Information
- <open question that blocks writing tests>
- ...
---
## Definition of Done
- [ ] <measurable completion criterion>
- [ ] Test plan approved (`plan it`)
- [ ] Regression tests generated by `test-writer` and passing
- ...
Writers put their own header block above ## User Story:
user-story-enhancer(WAY 6) titles the section## Enhanced User Storyinstead of## User Story, and appends the original body in a<details><summary>Original story (preserved)</summary>block after the DoDbenchmark-gap-story-writer(WAY 8) adds# US-<n> — <title>plus the Gap source / Target today / Priority · Effort lines
Every story body ends with the Output Watermark footer from CLAUDE.md.
Acceptance criteria rules
- Gherkin Given / When / Then
- Cover: main happy path, every variant mentioned, error flows, edge cases, and non-functional requirements if stated
- At least one negative/failure path per story
- "Then" must be concrete, observable, and assertable. Never "the system should work correctly"
- Priority:
mustfor core flows,shouldfor important variants,couldfor nice-to-haves - Number from AC-01 sequentially.
test-writertraces tests back to these IDs (**Covers:** AC-01), so never renumber existing ACs on a re-run. Append new ones instead
Test scenarios
Stories carry no Test Scenarios table: which tests to write, at which level and priority, is the test plan's job (test-plan skill, WAY 19), designed from these ACs with the categories of requirements-analysis §4. A story enhanced before WAY 19 may still have one: WAY 6 drops it on its next rewrite, and plan it reads its rows as hints.
Missing Information
Questions that block writing tests (the requirements-analysis §2 readiness gate), one per line. An empty section means
"nothing blocking", so write - none rather than deleting the heading.
e2e-session and write-tests stop and ask the user while any question here
is unanswered.
04 同仓库更多 Skills
write-tests
WAY 4 — write test cases only, no execution. Use when the user says "write it", "write tests", "generate test cases" — an approved test plan (`Plan:`), or requirements (text or a tracker issue) planned and approved first, optional App/Spec/MR or PR → exactly the planned test files.
verify-fix
WAY 9 — verify that a bug is fixed by running its regression test. Use when the user says "verify it", "verify fix", "is #142 fixed", "check the fix" with one or more bug refs (#142, SHOP-142), or "verify all" for every open bug that has a regression test.
tracker
Provider-neutral contract for every issue-tracker and code-host action (create/update/comment/close issues, attach files, comment on MRs/PRs, read CI runs and logs) plus label conventions and failure handling. Every WAY calls these operations; the matching provider-* skill says how to perform them on GitLab, GitHub, Jira, Azure DevOps, or Bitbucket.
traceability
WAY 14 — requirements traceability matrix for a user story (each acceptance criterion) or a test folder written from plain text (each R-NN requirement) → the tests covering it → their latest result → open bugs. Use when the user says "trace it", "traceability", "is #148 covered", "coverage of SHOP-148", "trace it <folder>".
test-plan
WAY 19 — design a test plan before any test code. Use when the user says "plan it", "plan tests", "test plan", "design tests" with requirements (text or a tracker issue), optional App/Spec/MR or PR. Output is the test plan (scope, levels, one row per Test#<nn> with category, tags, covers, priority, coverage, entry/exit criteria, risks), reviewed by `review-plan` (WAY 20), filed for approval; `write it Plan:` / `e2e it Plan:` then write exactly that plan. Also holds the plan format every other WAY reads.
session-report
Produce, save, and file the end-of-session QA summary for a WAY 1 (browser) or WAY 2 (API) run — execution counts, failed test cases, accessibility table (WAY 1), schema/performance flags (WAY 2), bugs filed. Replaces the former session-reporter agent.