---
id: dev-develop-story
agent: dev
title: Implementar uma story
inputs: [story]
outputs: [código, testes, File List atualizada, status InProgress→Ready for Review]
elicit: false
modes: [interactive, yolo, preflight]
---

# Implementar uma story

**Objetivo:** transformar uma story aprovada em código testado e rastreável, atualizando só as
seções do Dev Record — sem inventar escopo e sem tocar no que não é meu.

**Pré-condições:**
- A story existe e NÃO está em `Draft` (foi validada pelo @po). Se estiver em Draft, **pare** e
  reporte: implementar uma story não-validada é retrabalho garantido.
- A story tem critérios de aceite (ACs) e a seção de Testing. Se faltar, **pare** e devolva ao @sm.

## Passos

1. **Leia a story COMPLETA antes de tocar em código** — ACs, notas de dev, seção de Testing. A story
   tem tudo que você precisa; não carregue PRD/arquitetura a menos que a story mande explicitamente.
2. **Procure padrão existente antes de criar** (REUSE > ADAPT > CREATE). Se já existe um utilitário/
   componente que resolve, use; se quase resolve, adapte sem quebrar quem consome; só crie do zero
   quando nada serve — e registre o porquê.
3. **Implemente um AC por vez.** Para cada critério de aceite:
   a. escreva o código mínimo que satisfaz o AC, seguindo os padrões do projeto;
   b. escreva o teste que prova o AC (não marque o AC sem teste verde);
   c. rode `lint` + `typecheck` + os testes da área;
   d. **checkpoint de autocrítica** (a cada ~30 linhas): isto quebra algum consumidor? cobre o caso
      de erro? é o caminho feliz só?
4. **Atualize a File List** da story a cada arquivo criado/modificado. É o rastro do que você mexeu.
5. **Rode a verificação completa** antes de declarar pronto: lint limpo, typecheck 0, toda a suíte
   verde. Vermelho não vira "Ready for Review".
6. **Revisão de qualidade pré-commit** (`nexus run` review ou ferramenta configurada): rode na
   mudança não-commitada. CRITICAL → corrijo agora (máx. 2 iterações). HIGH → corrijo se der na 2ª
   iteração, senão registro como dívida. MEDIUM/LOW → registro, não bloqueio.
7. **Commit local** (`git add`/`git commit`, conventional commit com o id da story). **Nunca** `git
   push` — isso é do @devops; eu deixo pronto e delego a subida.
8. **Marque a story** `Ready for Review` e preencha Completion Notes + Change Log. Roteio para o @qa.

## Critério de pronto (DoD)

- [ ] Todos os ACs implementados, cada um com teste verde
- [ ] lint limpo, typecheck 0, suíte completa verde
- [ ] File List, Completion Notes e Change Log atualizados
- [ ] Revisão pré-commit sem CRITICAL aberto
- [ ] Commit local feito; nada de `git push` (delegado ao @devops)
- [ ] Só toquei nas seções do Dev Record da story — não em ACs, escopo ou título

## Falha / recuperação

- **Teste não passa após 3 tentativas no mesmo ponto** → HALT, registro no Debug Log e reporto o
  bloqueio em vez de empurrar com gambiarra.
- **CRITICAL da revisão persiste após 2 iterações** → HALT, não marco Ready for Review; reporto.
- **Descobri que a story está incompleta/ambígua no meio** → paro, registro a lacuna e devolvo ao
  @sm/@po. Não invento o requisito que falta.
- **A mudança exige tocar fora do meu escopo** (schema, infra, UI) → delego ao dono (@data-engineer,
  @devops, @ux-design-expert) em vez de invadir a lane.