AgentSkillsCN

user-story-builder

每当用户描述一个问题、功能需求或想要实现的任务，并需将其转化为结构清晰的用户故事时，都可运用此技能。触发条件包括“我想实现”、“我需要一个用户故事”、“帮我拟个故事”、“我有个问题……”或任何用户提出原始想法或问题、需在开发开始前正式化为用户故事的情形。在编写验收标准、界定范围或启动开发会议之前，务必先运用此技能。

SKILL.md
--- frontmatter
name: user-story-builder
description: "Use this skill whenever the user describes a problem, feature request, or task they want to implement and needs to turn it into a well-structured user story. Triggers on phrases like \"quero implementar\", \"preciso de uma história de usuário\", \"monta uma story para\", \"tenho um problema que\", or any situation where the user presents a raw idea or problem that needs to be formalized as a user story before development begins. Always use this skill before writing acceptance criteria, defining scope, or initiating a development session."

User Story Builder

Transforma um problema ou ideia bruta em uma user story bem definida, com critérios de aceitação claros, garantindo alinhamento completo entre o agente e o usuário antes de qualquer trabalho de desenvolvimento.

Protocolo

Fase 1 — Entendimento do problema

Ao receber um problema ou ideia, não escreva a story imediatamente.

Primeiro, faça perguntas cirúrgicas para eliminar ambiguidade. O objetivo é chegar em:

  1. •Quem é o usuário real que se beneficia (papel/persona, não "o sistema")
  2. •O que precisa ser feito — a ação concreta, não o mecanismo técnico
  3. •Por que — o valor de negócio ou técnico que justifica o esforço
  4. •Quando está pronto — o critério observável que indica conclusão

Regras para as perguntas:

  • •Máximo 3 perguntas por rodada
  • •Priorize as que desbloqueiam as outras
  • •Se o "para que" (o porquê) não estiver claro, essa é sempre a primeira pergunta
  • •Se o escopo parecer grande, pergunte sobre o menor slice que entrega valor

Exemplo de perguntas úteis:

  • •"Qual é o resultado observável quando isso estiver funcionando?"
  • •"Quem sofre hoje sem essa funcionalidade?"
  • •"Existe uma versão menor disso que já entregaria valor?"
  • •"O que está fora do escopo dessa story?"

Continue perguntando até ter clareza suficiente para escrever uma story que passe no critério INVEST (Independent, Negotiable, Valuable, Estimatable, Small, Testable).

Fase 2 — Draft da story

Com as respostas em mãos, escreva a story no template:

code
Como [tipo de usuário],
quero [ação concreta e pequena],
para que [resultado de negócio ou técnico mensurável].

Seguido dos critérios de aceitação:

code
Critérios de aceitação:
- [ ] [condição observável 1]
- [ ] [condição observável 2]
- [ ] [condição observável 3]

Regras para os critérios:

  • •Cada critério deve ser verificável sem ambiguidade
  • •Sem critérios de implementação (como, não o quê)
  • •Incluir explicitamente o que está fora do escopo se houver risco de expansão
  • •Máximo de 5 critérios. Se precisar de mais, a story está grande demais — proponha split.

Fase 3 — Alinhamento

Após apresentar o draft, pergunte explicitamente:

"Essa story captura o que você quer? Algum critério está errado, faltando ou além do escopo?"

Itere até o usuário confirmar que está alinhado. Só então a story está pronta.

Fase 4 — Saída final

Apresente a story confirmada em bloco formatado:

code
## História: [título curto]
 
Como [tipo de usuário],
quero [ação],
para que [valor].
 
### Critérios de aceitação
- [ ] ...
- [ ] ...
 
### Fora do escopo
- ...

Heurísticas de qualidade

A história está boa quando:

  • •O "para que" expressa valor real, não consequência técnica óbvia
  • •Qualquer desenvolvedor lendo entende o que está pronto sem perguntar
  • •Pode ser desenvolvida e entregue em uma sessão ou iteração curta
  • •Os critérios de aceitação são testáveis manualmente ou com testes automatizados

Sinais de que a história precisa de split:

  • •O "quero" contém "e" ou "ou"
  • •Tem mais de 5 critérios de aceitação
  • •O usuário hesita ao dizer se cabe em uma iteração
  • •Há dependência implícita de outra história não escrita

Sinais de que o "para que" está fraco:

  • •É uma consequência técnica ("para que o código fique mais limpo")
  • •Repete o "quero" com outras palavras
  • •Não mudaria nada se fosse removido