Iniciar Item de Trabalho (ADO)

Iniciar Item de Trabalho

Transforma um ticket ADO colado em: um branch novo (ou corretamente retomado), uma memória de contexto que sessões futuras podem retomar, descoberta fundamentada no código e, ou uma análise de causa raiz ou um layout de funcionalidade. Termina em um checkpoint — apresenta as descobertas e espera. Nenhum código de correção ou funcionalidade é escrito nesta habilidade; o usuário aprova a direção primeiro, porque uma RCA errada que é enviada rapidamente custa um ciclo completo de QA.

0. Carregar a configuração local

Leia config.local.md na pasta desta habilidade primeiro — antes de analisar o ticket. Ela contém os substantivos que esta habilidade deliberadamente não hard-coda: prefixo do branch, branch base, documento de camadas do projeto, onde as investigações ficam, pontos cegos do índice de código e memórias passadas que valem a pena apontar. A qualidade da descoberta depende desses detalhes, então não pule isso.

Se estiver faltando (instalação nova), infira o que puder — branch base de git remote show origin (branch HEAD), prefixo dos branches existentes do usuário (git branch --list "*/*") — diga ao usuário o que você inferiu e ofereça salvar como config.local.md (veja config.example.md).

O diretório de memória é aquele que seu prompt de sistema nomeia para este projeto; o repositório é aquele em que você está trabalhando. Nenhum deles precisa de configuração.

1. Analisar o ticket

Extraia, do que foi colado. A cópia de página do ADO é ruidosa: a primeira linha é o tipo e o ID em maiúsculas (USER STORY 12345, BUG 12346), cada rótulo de campo está em sua própria linha com o valor na próxima (State / Dev In Progress), tags aparecem como linhas soltas perto do topo, e há cromo da interface para ignorar (Save, Follow, Click to add …, switch to HTML editor, seções vazias do TestRail). Imagens e anexos não sobrevivem à colagem.

• ID (número) e Tipo de Item de Trabalho — Bug vs. História de Usuário / Funcionalidade / PBI / Tarefa. Se o tipo não for informado, infira-o (etapas de reprodução + esperado/real ⇒ bug; "Como um … eu quero" ou critérios de aceitação ⇒ funcionalidade) e diga o que inferiu.
• Título, Estado, Área/Iteração se presentes
• Bug: etapas de reprodução, esperado vs. real, número da build, plataforma/dispositivo/SO, links profundos, nomes de logs anexados, capturas de tela mencionadas
• Funcionalidade: descrição, critérios de aceitação, designs vinculados, nomes de feature flags / experimentos
• Discussão/comentários: tentativas anteriores, notas de QA e suas datas, números de PR

Se não houver ID, peça por ele antes de criar qualquer coisa — o ID dirige o branch e os nomes da memória. Observe qualquer coisa referenciada mas não visível (capturas de tela, logs) para que possa perguntar sobre ela no checkpoint em vez de adivinhar seu conteúdo.

2. Branch

Execute git no repositório em que você está trabalhando (se a sessão estiver em uma worktree ou outro clone, use esse — nunca cd para longe dele):

git status --porcelain

Se a árvore estiver suja, pare. Liste os arquivos e o branch atual, e pergunte como proceder (carregar, stash, ou commit no branch antigo). Arquivos não commitados de um item vazam para os commits do próximo; o usuário decide isso, não você.

Quando limpo:

git fetch origin
git branch --list "<prefixo>/<id>*"; git branch -r --list "origin/<prefixo>/<id>*"

Se nenhum branch existir para o ID, corte <prefixo>/<id> de origin/<base> e registre o SHA curto (git rev-parse --short HEAD).

Se <prefixo>/<id> ou <prefixo>/<id>-N já existir (local ou remoto), veja o mais novo antes de decidir — o mesmo ID pode chegar em três momentos muito diferentes:

git log --oneline origin/<base>..<prefixo>/<id>[-N]   # commits não mesclados?
git log --oneline origin/<base> --grep=<id>           # "Merged PR NNNN: ... <id>" = foi mesclado

ADO faz squash-merge, então um branch mesclado ainda mostra seus commits como "à frente" da base — a linha Merged PR no branch base é o que diz que ele pousou. Leia isso junto com o Estado do ticket e a data do comentário de QA mais novo versus o último commit do branch.

Branch existente mais novo	Estado típico do ticket	O que fazer
Sem commits além de origin/<base> (geralmente o branch em que você está — o usuário o cortou antes de colar)	Novo / Em Desenvolvimento	Reutilize-o. Faça checkout, git merge --ff-only origin/<base>.
Mesclado (um Merged PR para este ID na base) e QA falhou desde então	Ativo / Reaberto, comentário de QA com falha mais novo que o merge	Corte o próximo sufixo (-1, -2, …) de origin/<base>; a tentativa anterior torna-se material de descoberta primordial.
Commits não mesclados (enviados ou não), ou um PR ainda aberto	Revisão de PR / Pronto para Teste / Em Progresso	Em andamento — não crie branch. Relate o que está nele (commits, se foi enviado, quão atrás da base está), torne-o assunto da descoberta, e pergunte se deve retomar ou começar uma nova tentativa.

Se os sinais discordarem (ex.: estado diz Novo mas há um branch não mesclado), trate como em andamento e pergunte — cortar um branch duplicado é o erro caro. Se git fetch falhar (VPN / auth), diga isso e use o origin/<base> local, notando que a base pode estar desatualizada.

Não faça push e não faça commit — o usuário não pediu.

3. Memória de contexto (escreva agora, atualize depois)

Escreva a memória antes da descoberta, com status ⏳, para que o item seja retomável mesmo se a sessão morrer no meio da investigação. Use references/memory-template.md.

• Bug → bug-<id>-context.md, funcionalidade/história/tarefa → feature-<id>-context.md
• Se já existir uma para este ID, atualize-a em vez de criar uma segunda — e corrija nela qualquer coisa que o estado do git agora contradiga.
• Adicione um ponteiro de uma linha para MEMORY.md. Sem ele, sessões posteriores nunca encontram a memória.

4. Descoberta no código

O objetivo é encontrar os caminhos de código reais que o ticket toca e o histórico em torno deles — o suficiente para que a RCA/layout cite arquivo:linha, não palpites.

• Use o índice de código se houver um (CodeGraph, LSP): comece com uma consulta de contexto nos substantivos do ticket (página, controle, serviço, DTO), depois uma chamada de exploração no que ele superficia; chamadores/impacto no símbolo suspeito. Verifique na configuração os pontos cegos do índice (tipos de arquivo que ele não analisa) e faça grep nesses em vez disso.
• Rotas e nomes de UI: rotas de página, nomes de componentes, classes CSS e esquemas de link profundo do ticket são bons termos de grep.
• Trabalho anterior: git log --oneline --all --grep=<id>, git log --oneline -20 -- <arquivos suspeitos>, a pasta de docs/investigações do projeto (config) e o diretório de memória para escritos sobre a mesma área. Uma correção anterior para o mesmo sintoma que falhou no QA é a coisa mais valiosa que você pode encontrar.
• Compare os casos de sucesso e falha. Quando o QA lista casos que passam e um que falha, descubra o que realmente difere entre eles no código — a página hospedeira, o caminho de dados, o tempo — antes de decidir um mecanismo.
• Cada host/plataforma: se a UI for compartilhada entre hosts (mobile shell, web), verifique se o ticket é específico de plataforma e se o código é.
• Não construa durante a descoberta. Ler código é suficiente aqui; builds são lentos e pertencem à implementação.

Para varreduras amplas em muitas pastas, um subagente Explore é adequado; para uma área conhecida, faça diretamente.

5a. Bug → análise de causa raiz

Use a habilidade superpowers:systematic-debugging para o método se estiver disponível. O padrão é medido, não adivinhado: nomeie o mecanismo e o arquivo:linha exato, e explique por que ele produz precisamente o sintoma relatado e não algum outro (por que o caso com falha falha e os casos de sucesso passam).

• Trace o caminho da ação do usuário nas etapas de reprodução até o estado defeituoso. Cite as linhas relevantes.
• Reproduza onde viável sem um dispositivo: testes de componente para estado/marcação, uma réplica estática headless-browser para problemas de layout/rolagem/CSS (a configuração pode apontar para uma memória descrevendo um harness existente). Se não puder reproduzir, diga isso claramente, declare sua confiança e que evidência a confirmaria (ex.: uma linha de log específica ou captura de tela do QA).
• Separe a causa raiz de fatores contribuintes e de problemas adjacentes que pertencem a outros tickets.
• Proponha uma direção de correção (ou 2–3 opções com uma recomendação) e o teste de regressão que a fixaria — mas não os escreva ainda.
• Item em andamento (passo 2): a RCA se torna uma revisão da correção já no branch — ela aborda a falha de QA mais nova, e que riscos residuais a fariam falhar no dispositivo? Recomende retomá-la e diga qual resultado de QA justificaria uma nova tentativa.

5b. Funcionalidade → layout e elaboração

Use a habilidade superpowers:brainstorming para a conversa de design se estiver disponível.

Primeiro, julgue se os critérios de aceitação são suficientes. Eles são suficientes quando:

• cada CA pode ser transformado em uma asserção de teste concreta e mapeado para um arquivo a tocar, e
• estados de UI (carregando, vazio, erro, desabilitado), comportamento por plataforma, eventos de analytics e feature flagging são ou especificados ou claramente não aplicáveis.

Se forem suficientes, não faça perguntas por fazer — apresente o layout da funcionalidade. Se não forem, a elaboração é necessária: pergunte apenas sobre as lacunas, em lote em um AskUserQuestion (até 4 perguntas, opções concretas, um padrão recomendado primeiro). CAs vagos que são adivinhados produzem retrabalho.

Classifique cada lacuna antes de perguntar: se a resposta mudaria o design (o que é mostrado, de onde vêm os dados, o que o usuário vê ao tocar), é uma pergunta. Se for algo com uma convenção de casa óbvia — uma chave de feature flag, um nome de evento de analytics, um registro DI — escolha o valor convencional, escreva no layout como Assumido: para que o usuário possa corrigir rapidamente, e não pergunte. O lote de 4 perguntas é todo o pedido; nenhuma "também, por favor confirme…" após ele, porque isso são apenas mais perguntas sem opções.

O layout cobre:

• Arquivos a adicionar/modificar, colocados de acordo com as camadas do projeto (a configuração aponta para o documento que as define), incluindo registro DI em cada host
• Fluxo de dados: de onde vêm os dados, qual serviço possui o estado, como ele alcança o componente
• Mapeamento CA → teste, nomeando o projeto de teste para cada um
• Diferenças de plataforma, analytics/flags, riscos e perguntas em aberto

6. Checkpoint

Atualize o arquivo de memória com o que você encontrou (status 🔄, resumo da causa raiz ou layout, perguntas em aberto), então apresente ao usuário:

Bug:

## Bug <id>: <título>
Branch: <prefixo>/<id> (de origin/<base> @ <sha>)   — ou: em andamento em <branch>, sem novo branch
Memória: bug-<id>-context.md

### Causa raiz
<mecanismo, arquivo:linha, por que corresponde ao sintoma> — Confiança: <alta/média/baixa + o que a elevaria>

### Evidência
<citações de código, resultados de reprodução, histórico: PRs/tentativas anteriores>

### Correção proposta
<direção ou opções + recomendação; teste de regressão a adicionar; arquivos a tocar>

### Preciso de você
<capturas de tela/logs faltando, decisões>

Funcionalidade:

## Funcionalidade <id>: <título>
Branch / Memória: ...

### O que os CAs dizem vs. o que está faltando
### Layout proposto (arquivos, fluxo de dados, CAs → testes, cada plataforma, Assumido: …)
### Perguntas  (ou "Nenhuma — os CAs são suficientes")

Então pare e espere aprovação. Se a RCA ou o layout abranger 5+ arquivos ou mudar a arquitetura, ofereça escrevê-lo na pasta de docs/investigações do projeto (config) — ofereça, não crie automaticamente.