pwdev-solucoes User Stories Skill
Standard of quality for every user story produced by the PWDEV-CODE framework
(/pwdev-code:product prd §6, /pwdev-code:product stories) and for
reviewing stories brought by the human.
1. Canonical Format
PT-BR: Como {persona}, quero {ação}, para {valor/resultado}.
EN: As a {persona}, I want {action}, so that {value/outcome}.
- Persona — a real user type with a name from the PRD/requirements (never "o sistema"/"the system"; never "usuário" genérico if personas exist).
- Ação — one capability, observable from the user's perspective.
- Valor — the reason; if you can't state it, the story probably isn't one.
2. INVEST — quick test per letter
| Letter | Question | Fails when... |
|---|---|---|
| Independent | Can it ship without waiting on another story? | hidden dependency on an unwritten story |
| Negotiable | Is it an intent, not a frozen spec? | prescribes UI pixel/implementation detail |
| Valuable | Does the persona gain something? | value only for developers ("refactor X") |
| Estimable | Can the team size it? | too vague or research-shaped |
| Small | Fits in one iteration? | it's an epic wearing a story costume |
| Testable | Can each AC be verified objectively? | "should be fast/easy/intuitive" |
A story that fails 2+ letters must be rewritten or split before entering
.planning/product/stories/.
3. Acceptance Criteria
Use Gherkin when behavior has state + trigger + observable result:
# PT-BR # EN
Dado que estou logado como cliente Given I am logged in as a customer
Quando adiciono um item esgotado When I add an out-of-stock item
Então vejo a mensagem "indisponível" Then I see the "unavailable" message
E o item não entra no carrinho And the item is not added to the cart
Use a simple checklist for cross-cutting or static criteria (e.g. "- [ ] lista pagina de 20 em 20", "- [ ] AA contrast on all states").
Rules: every AC is objectively verifiable; cover the happy path AND at least one error/edge path; 3-8 ACs per story (more → split the story).
4. Definition of Ready
A story is status: ready only when:
- Canonical format with a named persona
- Passes all 6 INVEST letters
- 3-8 verifiable ACs (happy + error path)
- Priority assigned (MoSCoW)
- Dependencies declared (or "none")
- Out-of-scope noted when the title invites scope creep
5. Anti-Patterns
| Never write | Why | Instead |
|---|---|---|
| "Como sistema, quero..." | systems don't want things | name the persona who benefits |
| Technical story disguised ("Como dev, quero migrar o banco") | no user value stated | attach it to the user outcome, or make it a task in a plan |
| AC "deve ser rápido/fácil/intuitivo" | not testable | number it ("responde em <500ms", "máx 2 cliques") |
| Story-epic ("Como cliente, quero gerenciar meu pedido") | not Small | split per capability (ver, cancelar, alterar) |
| Hidden dependency ("...igual à tela de admin") | not Independent | declare the dependency or inline the requirement |
| UI prescription ("quero um dropdown azul...") | not Negotiable | state the need; design decides the control |
6. Review Checklist (10 items)
- Persona named and real (exists in PRD/requirements)?
- One capability per story?
- Value clause non-circular ("para que eu possa fazer X" ≠ repetir a ação)?
- INVEST: all 6 pass?
- ACs: happy path covered?
- ACs: at least one error/edge path?
- ACs: all objectively verifiable (numbers, observable states)?
- Priority MoSCoW assigned?
- Dependencies explicit?
- Language consistent with project
lang(terms técnicos em inglês)?
7. Examples
✅ Good (PT-BR)
US-03 — Cancelar pedido não enviado Como cliente, quero cancelar um pedido que ainda não foi enviado, para não pagar por algo que não quero mais. ACs: Dado pedido "processando" / Quando clico Cancelar e confirmo / Então status vira "cancelado" E estorno é criado E recebo e-mail. + Dado pedido "enviado" / Quando abro o pedido / Então Cancelar não é exibido.
✅ Good (EN)
US-07 — Export report as CSV As an operations analyst, I want to export the monthly report as CSV, so that I can cross it with the ERP spreadsheet. ACs: Given a report with data / When I click Export / Then a CSV downloads with the visible columns and filters applied. Given an empty report / Then Export is disabled with a tooltip.
❌ Bad → fixed
"Como usuário, quero uma tela de pedidos melhor."— persona genérica, não testável, não estimável. → "Como cliente recorrente, quero filtrar meus pedidos por status e período, para encontrar uma compra antiga sem rolar a lista inteira."
"As a system, I want to validate tokens."— system persona, technical. → "As a logged-in user, I want my session to stay valid while I work, so that I don't lose a form to a silent logout." (token validation becomes a task under this story's plan)
8. Integration with PWDEV-CODE
/pwdev-code:product prd§6 (User Stories with ACs) MUST follow this skill./pwdev-code:product storiesuses this skill as the quality bar and persists stories to.planning/product/stories/US-{NN}-{slug}.md.discover/designconsult existing stories as requirement sources.- Story files carry frontmatter:
id,epic(roadmap ref, if any),priority(MoSCoW),status: draft|ready.