feat: separa dados de usuário e experiência (issue #2)

.github/skills/issue-to-brief/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: issue-to-brief
+description: Analisa uma issue do GitHub e transforma em um briefing tecnico acionavel para este projeto Spring Boot. Use antes de implementar, quando o pedido envolver issue, ticket, backlog, bug, feature, requisito ou criterios de aceite, para mapear impacto no codigo, preservar contrato HTTP e preparar handoff para refactor e testes.
+argument-hint: [issue] [contexto adicional] [restricoes ou contrato a preservar]
+---
+
+# Issue To Brief
+
+Esta skill conduz a etapa de entendimento e preparacao antes da implementacao.
+
+## Quando usar esta skill
+
+Use esta skill quando precisar:
+
+- ler uma issue do GitHub e converter em briefing tecnico objetivo
+- separar escopo confirmado de suposicoes antes de codar
+- mapear impacto provavel no backend Spring Boot deste repositorio
+- preparar handoff claro para refactor e para testes
+
+Nao use esta skill para resumir o trabalho ja concluido. Nesse caso, use a skill `pr-summary`.
+
+## Objetivo
+
+Reduzir ambiguidade da issue e deixar a implementacao pronta para seguir com contexto suficiente para os proximos agents.
+
+## Procedimento
+
+1. Ler a issue e, se existirem, comentarios, checklist, labels e criterios de aceite via GitHub MCP.
+2. Resumir o objetivo funcional em linguagem direta.
+3. Separar fatos confirmados de inferencias.
+4. Mapear impacto provavel no codigo deste repositorio.
+5. Destacar invariantes observaveis que nao devem mudar.
+6. Preparar um handoff explicito para o custom agent de refatoracao.
+7. Preparar um handoff explicito para o custom agent de testes.
+
+## Saida obrigatoria
+
+Responder com estas secoes, nesta ordem:
+
+```text
+Resumo da issue
+- Objetivo:
+- Contexto:
+- Criterios de aceite:
+
+Escopo confirmado
+- O que precisa mudar:
+- O que nao foi pedido:
+
+Impacto provavel no codigo
+- Controller:
+- Service:
+- Repository:
+- Entity:
+- DTO:
+- Util/Exception:
+- Testes existentes relacionados:
+
+Invariantes e restricoes
+- Contrato HTTP a preservar:
+- Headers relevantes:
+- Estrutura de sucesso e erro:
+- Restricoes tecnicas:
+
+Pontos em aberto
+- Duvidas:
+- Suposicoes adotadas:
+
+Handoff para refactor
+- Arquivos ou classes candidatas:
+- Resultado esperado:
+- Cuidados obrigatorios:
+
+Handoff para test
+- Classes a validar:
+- Cenarios minimos:
+- Evidencias esperadas:
+```
+
+## Como analisar neste repositorio
+
+Ao analisar impacto provavel, considerar primeiro:
+
+- `src/main/java/br/com/devsuperior/dev_xp_ai/controller`
+- `src/main/java/br/com/devsuperior/dev_xp_ai/service`
+- `src/main/java/br/com/devsuperior/dev_xp_ai/repository`
+- `src/main/java/br/com/devsuperior/dev_xp_ai/entity`
+- `src/main/java/br/com/devsuperior/dev_xp_ai/dto`
+- `src/main/java/br/com/devsuperior/dev_xp_ai/exception`
+- `src/main/java/br/com/devsuperior/dev_xp_ai/util`
+- `src/test/java/br/com/devsuperior/dev_xp_ai`
+
+## Como preencher a saida
+
+- Em `Resumo da issue`, priorize objetivo funcional, contexto operacional e criterios de aceite explicitos.
+- Em `Escopo confirmado`, diferencie pedido explicito de extrapolacao tecnica.
+- Em `Impacto provavel no codigo`, cite apenas camadas plausiveis; se uma camada nao parecer afetada, diga isso.
+- Em `Invariantes e restricoes`, trate contrato HTTP observavel como item critico: path, verbo, status, headers e JSON.
+- Em `Pontos em aberto`, registre lacunas reais antes de sugerir implementacao.
+- Nos handoffs, escreva instrucoes que possam ser usadas diretamente pelos agents `refactor` e `test`.
+
+## Regras
+
+1. Nao comecar implementando.
+2. Nao inventar requisito ausente na issue sem marcar como suposicao.
+3. Se a issue tocar endpoint existente, explicitar que path, verbo, status code, headers e JSON observavel devem ser preservados salvo pedido explicito em contrario.
+4. Se a issue estiver incompleta, registrar as lacunas antes do handoff.
+5. Sempre produzir handoff utilizavel pelos custom agents `refactor` e `test`.
+
+## Como preparar o handoff para os agents
+
+Para o `refactor`:
+
+- dizer qual comportamento deve ser criado ou alterado
+- listar classes e pacotes provaveis
+- destacar contrato HTTP e restricoes de persistencia
+- apontar riscos de regressao
+
+Para o `test`:
+
+- listar classes alteradas ou provaveis
+- informar cenarios de sucesso e erro
+- cobrar validacao de status, body, headers e cobertura
+
+## Exemplo de uso
+
+Entrada:
+
+```text
+/issue-to-brief issue #456 sobre ajuste de validacao no endpoint de clientes sem mudar o contrato HTTP
+```
+
+Saida esperada:
+
+- briefing com escopo confirmado e lacunas visiveis
+- impacto provavel no codigo deste projeto
+- handoff claro para refactor e para test
+
+## Resultado esperado
+
+Um bom resultado reduz ambiguidade da issue e deixa a implementacao pronta para seguir, com contexto suficiente para o agent de refatoracao atuar primeiro e o agent de testes atuar em seguida.

.github/skills/pr-summary/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pr-summary
+description: Gera um resumo tecnico final de implementacao para demo, comentario de pull request ou fechamento de tarefa. Use quando a mudanca ja tiver sido implementada e validada e voce precisar consolidar evidencias, testes, cobertura, riscos e relacao com a issue sem inventar fatos.
+argument-hint: [issue ou contexto] [arquivos alterados] [testes/comandos executados]
+---
+
+# PR Summary
+
+Esta skill conduz o fechamento tecnico depois da implementacao e da validacao.
+
+## Quando usar esta skill
+
+Use esta skill quando precisar:
+
+- transformar uma implementacao concluida em um resumo final apresentavel
+- preparar texto para comentario de PR, demo ou encerramento de tarefa
+- consolidar mudancas, testes executados, cobertura, riscos e pendencias com base em evidencia
+
+Nao use esta skill para entender uma issue antes de implementar. Nesse caso, use a skill `issue-to-brief`.
+
+## Objetivo
+
+Produzir um resumo final consistente, auditavel e facil de apresentar, preservando a separacao entre fato observado e inferencia.
+
+## Procedimento
+
+1. Reunir o contexto da issue original.
+2. Reunir o que foi alterado no codigo de producao.
+3. Reunir o que foi alterado nos testes.
+4. Consolidar comandos executados e seus resultados relevantes.
+5. Consolidar cobertura, quando disponivel.
+6. Registrar riscos, limitacoes e pendencias.
+7. Fechar com uma relacao explicita entre issue, implementacao e validacao.
+
+## Saida obrigatoria
+
+Responder com estas secoes, nesta ordem:
+
+```text
+Resumo final
+- Issue:
+- Objetivo entregue:
+
+Implementacao
+- O que mudou:
+- Principais classes afetadas:
+- Decisoes tecnicas relevantes:
+
+Testes e validacao
+- Testes criados ou ajustados:
+- Comandos executados:
+- Resultado dos testes:
+- Cobertura JaCoCo:
+
+Contrato e riscos
+- Contrato HTTP preservado ou alterado:
+- Riscos e limitacoes:
+- Pendencias:
+
+Pronto para PR
+- Resumo curto para PR:
+- Relacao com a issue:
+```
+
+## Como preencher a saida
+
+- Use apenas fatos que estejam visiveis no contexto, no diff, nos arquivos alterados ou nos resultados de comando.
+- Se algum ponto relevante nao estiver disponivel, diga explicitamente que a evidencia nao foi encontrada.
+- Ao mencionar cobertura, informe numeros somente quando houver relatorio ou saida concreta.
+- Ao mencionar contrato HTTP, deixe claro se o contrato foi preservado ou alterado e cite o que mudou.
+- Ao mencionar riscos, prefira riscos observaveis, regressivos ou de rollout, e nao frases genericas.
+
+## Regras
+
+1. Nao afirmar execucao, cobertura ou sucesso de testes sem evidencia no contexto.
+2. Separar claramente fato observado de inferencia.
+3. Se nao houver cobertura disponivel, dizer explicitamente.
+4. Se a issue tiver criterios de aceite, dizer como cada um foi atendido ou o que ficou pendente.
+5. Se houve mudanca de contrato HTTP, explicitar de forma objetiva e concreta.
+
+## Exemplo de uso
+
+Entrada:
+
+```text
+/pr-summary issue #123, alteracoes no endpoint de pedidos, testes de integracao executados
+```
+
+Saida esperada:
+
+- resumo final com secoes fixas
+- relacao objetiva entre issue, implementacao e validacao
+- riscos e pendencias explicitados sem exagero
+
+## Fechamento curto para demonstracao
+
+Quando fizer sentido, termine com um bloco curto de resumo executivo contendo:
+
+- objetivo da issue
+- o que foi implementado
+- como foi validado
+- se esta pronto para revisao/PR
+
+## Resultado esperado
+
+Um bom resultado deixa a demo com um encerramento claro: contexto da issue, implementacao feita, testes executados, cobertura reportada e riscos remanescentes.