issue-flow

Issue Flow — Analista / Desenvolvedor em um rastreador de issues compartilhado

Contrato de Ativação

Use para issue-flow analyst [condições], issue-flow dev [regras-de-domínio] [número-da-issue], trabalho de analista ou desenvolvedor, reivindicações, e transições de estado do fluxo de trabalho. Condições do analista e domínios do desenvolvedor são opcionais: um alvo delimitado é o escopo; caso contrário, o analista audita o repositório e o desenvolvedor implementa a issue selecionada. Leia as instruções do repositório primeiro e carregue apenas a vinculação do rastreador selecionada pela configuração do operador antes do trabalho no rastreador. Carregue composição de domínio para regras de transferência, prioridade ou roteamento; notas de execução para invocação, delegação ou mecânica de equipe; e incidentes de segurança para lógica de corrida, recuperação, transferência ou falha.

Regras Rígidas

• O Issue Flow é dono dos papéis, estados, reivindicações e transições; os domínios roteados são donos do valor, prioridade, evidência e critérios de conclusão. Nenhum lado inventa a política do outro.
• Um analista, incluindo um revisor adversarial, é somente leitura para o repositório e todo sistema externo, exceto as operações do rastreador configuradas necessárias abaixo: ele não cria branch/worktree/commit/PR e não executa migração, sincronização, gravação em banco de dados ou ação de entrega. Ele registra no máximo uma issue baseada em evidências. A revisão DEVE usar um contexto que não escreveu a alteração.
• Crie um run-id <runtime>-<prefixo-da-sessão> e reutilize-o para cada gravação. Mantenha a atribuição de execução limitada em rótulos analyst:<runtime>/dev:<runtime> e a atribuição de execução ilimitada em texto; os rótulos do analista persistem, enquanto os rótulos do desenvolvedor são removidos na liberação, mas retidos na entrega.
• Retome a issue mantida desta execução antes de consultar filas. Use a reivindicação adjudicada por linha do tempo da vinculação selecionada; a reivindicação ativa mais antiga vence. Execute verify_claim antes da primeira gravação no repositório, a cada batida cardíaca, e em cada limite caro ou irreversível; uma superfície de controle ilegível não permite gravação.
• Mantenha exatamente um de analysis, ready, in-progress, review, blocked, ou done. O estado do fluxo de trabalho da vinculação é autoritativo; toda projeção configurada é atualizada e relida, e done é explícito antes do fechamento do rastreador.
• A vinculação selecionada DEVE mapear ensure_states, create, list_state, claim, reclaim, verify_claim, heartbeat, transition, comment, last_activity, label, unassign, publish_version, e close. Execute operações reversíveis executáveis em vez de reconstruí-las; as vinculações DEVEM declarar capacidades não suportadas e falhar fechado.
• Critérios de aceitação da issue, regras de domínio roteadas e regras do repositório definem a conclusão. Nunca invente portões ausentes ou reinterprete a issue silenciosamente.

Portões de Decisão

Situação	Ação
Analista tem condições ou um diff/PR/issue delimitado	Analise apenas esse escopo sob as regras de repositório e domínio aplicáveis.
Analista não tem condições ou domínio	Use o contrato autônomo general em composição de domínio; registre apenas a descoberta mais forte deduplicada ou nada.
Uma rota de domínio é registrada	O analista carrega o livro de regras da esquerda; o desenvolvedor carrega o da direita. Declare explicitamente quando o roteamento de implementação está ausente.
Mecânica de execução ou aquisição de contexto independente variam	Siga notas de execução; limites de execução mudam o mecanismo, nunca o invariante.
A segurança de reivindicação, recuperação ou transferência precisa de lógica	Siga a vinculação ativa e incidentes de segurança, sem copiar a narrativa do incidente aqui.
O estado deve ser escolhido	Especificação inválida -> analysis; implementável e não atribuído -> ready; construção reivindicada -> in-progress; construída/publicada -> review; espera externa não construída -> blocked com condição e responsável; mesclada e verificada -> done.

Etapas de Execução

Antes da primeira gravação do rastreador de qualquer papel em um projeto desconhecido, execute os ensure_states da vinculação selecionada; então use as operações executáveis e leituras dessa vinculação em vez de reconstruí-las. Carregue composição de domínio para roteamento, validação de escala, particionamento de fila ou fallback autônomo; notas de execução para invocação, aplicação de somente leitura, aquisição de contexto independente ou limites de execução; incidentes de segurança apenas quando a lógica de reivindicação, recuperação, transferência ou falha for necessária; e entrega de repositório apenas quando as regras do repositório não definirem completamente isolamento ou integração.

Analista

1. Mantenha o repositório e sistemas externos não-rastreador como somente leitura. Processe analysis do mais antigo para o mais novo, depois inspecione blocked: mova condições resolvidas para ready com evidência, date condições que ainda são válidas e nomeie por quanto tempo uma pessoa deve qualquer decisão pendente.
2. Analise apenas o escopo delimitado sob o livro de regras de domínio esquerdo. Sem condições ou domínio, use o contrato autônomo general; verifique evidência e duplicatas, então mantenha no máximo a descoberta mais forte defensável ou relate que nenhuma sobreviveu.
3. Valide os campos, rota, escala e contrato de corpo para descobertas em fila e novas. Para trabalho em fila, adicione material de transferência ausente com comment e faça a transição apenas desse mesmo item completo; nunca crie um substituto. Para uma nova descoberta, preencha o modelo de issue do analista e create com todos os marcadores mais analyst:<runtime> e atribuição de run-id. Use ready, ou blocked com a condição exata ausente e responsável; então PARE sem implementar ou atribuí-lo.

O que o analista produz

Uma issue que um desenvolvedor pode pegar sem refazer a análise. Se o desenvolvedor tiver que re-derivar seu raciocínio, a análise não valeu nada.

## Description for dumb humans

> [!NOTE]
> Uma ou duas frases, linguagem simples, sem jargão, sem caminhos de arquivo, sem métricas — sobre o que é esta issue, para alguém que nunca lerá além desta linha. Escrito no idioma que a configuração do operador nomeia para esta instalação (veja a tabela no final deste arquivo). O cabeçalho em si é o título literal fixo acima — sempre em inglês, sempre essa frase exata, nunca reformulado por issue. `> [!NOTE]` é a sintaxe de alerta nativa do GitHub — ele renderiza como um callout com borda e cor, que é o objetivo: precisa ser visualmente impossível de perder em uma issue, caso contrário, cheia de prosa técnica.

Esta é a primeira coisa na issue, antes de `## Problem`.

## Problem
O que está errado ou faltando, e como você sabe. Evidência, não afirmação: referências arquivo:linha, números medidos, logs, etapas de reprodução.

## Why it matters
Impacto se deixado como está. Se você não puder declarar um, diga isso claramente — um "baixo impacto, registrado para completude" documentado é honesto e permite que o desenvolvedor despriorize.

## Proposed approach
O design. Alternativas que você considerou e por que as rejeitou. Se você NÃO está confiante, diga qual parte é incerta e o que a resolveria.

## Acceptance criteria
Afirmações verificáveis. "Mais rápido" não é um critério; "p95 abaixo de 200 ms medido por X" é. Inclua o que NÃO deve mudar (invariantes, saídas byte-idênticas).

## Out of scope
O que um desenvolvedor explicitamente não deve fazer aqui. Isso evita o aumento de escopo de forma mais confiável do que qualquer quantidade de prosa nas seções acima.

## Evidence
Comandos executados, arquivos lidos, números medidos. Suficiente para que um revisor possa verificar novamente a análise sem repeti-la.

Desenvolvedor

1. Retome a issue mantida desta execução em seu estado registrado antes de consultar filas. Caso contrário, processe review não atribuído antes de ready, verificando novamente o bloqueador de entrega antes de reivindicar trabalho publicado.
2. Para ready, particione candidatos válidos por domínio estável e escala declarada, classifique apenas dentro de cada partição e escolha o cabeça de partição mais antigo; um domínio selecionado limita a seleção ao seu item mais antigo de classificação mais alta. Use o mais antigo primeiro apenas quando nenhum candidato tiver um contrato de escala válido.
3. claim com o run-id e horizonte, depois adjudique a linha do tempo com timestamp do servidor; a reivindicação ativa mais antiga vence, e um perdedor comenta, libera e seleciona novamente. Mantenha o trabalho de revisão reivindicado em review a menos que uma mudança de código exija in-progress e um novo ciclo de publicação/revisão/CI; para trabalho pronto, faça a transição uma vez para in-progress com dev:<runtime> e nenhum segundo evento de reivindicação.
4. Carregue o livro de regras de implementação do lado direito da rota antes de planejar; se ausente, declare que nenhum se aplica e construa de acordo com os critérios de aceitação escritos. Siga as regras do repositório, use o fallback de entrega do repositório para política de isolamento/integração ausente, verifique a reivindicação imediatamente antes da primeira gravação de branch/worktree/arquivo e implemente no checkout isolado.
5. Renove antes de publicar, publique ou reutilize o alvo de revisão compartilhado, depois faça a transição para review. Adquira um contexto independente apenas quando Review delegation autorizar esta execução; caso contrário, solicite uma revisão iniciada separadamente. Exija seu veredito e CI verde na mesma exata cabeça/base; cada push invalida ambos. Deixe a entrega bloqueada em review, restaure o estado local alterado pela tentativa falha, registre o bloqueador preciso e desatribua em vez de contorná-lo; regras de repositório conflitantes merecem uma issue separada.
6. Renove em cada limite irreversível; mescle apenas quando revisado, verde e as identidades atuais de cabeça/base coincidirem. Para uma rota de merge-commit, exija que os pais exatos do SHA entregue sejam a base e a cabeça revisados; outras estratégias configuradas exigem sua topologia equivalente declarada pela vinculação e qualquer portão de SHA entregue. Para cada versão alterada, publique e verifique remotamente sua tag anotada imutável e Release exigida; renove novamente, faça a transição para done, registre revisão/CI/testes/medições/PR/SHA de entrega/publicações com o run-id e feche. Na transferência, preserve toda a evidência: especificação errada vai para analysis, espera externa não construída para blocked, trabalho construído não entregável para review e um diagnóstico parcial útil para ready.

Portão de revisão detalhado retido até a fatia final de aposentadoria

6. Obtenha a alteração publicada revisada por um contexto que não a escreveu, então exija CI verde na cabeça mais recente do PR. Capture os SHAs da cabeça e base antes da revisão e exija que o artefato do veredito nomeie ambos explicitamente; um "aprovado" flutuante não é evidência para nenhuma revisão ou diff específico. Onde a configuração autoriza, obtenha esse contexto você mesmo — um subagente ou colega de equipe; onde não autoriza, entregue o PR para uma execução de analista iniciada separadamente e diga na issue que você está esperando por ela. O que a configuração decide é quem inicia a revisão, nunca se ela é executada. Cada push invalida o veredito anterior e o resultado de CI: revise novamente a superfície alterada e aguarde as verificações exigidas novamente.

   Se a revisão, CI ou entrega estiver bloqueada, PARE ALI e deixe em review. Trabalho que está construído e publicado, mas não pode ser enviado — um revisor solicita alterações, uma verificação falha, aprovação nativa necessária não pode ser fornecida por uma identidade distinta, uma permissão está faltando, duas regras de projeto se contradizem — é trabalho concluído aguardando entrega, que é exatamente o que review significa. Não o mova para done: esse estado significa entregue. Não contorne o bloqueador também; uma regra que você ignora para enviar é uma regra que deixa de significar qualquer coisa.

   Comente o bloqueador precisamente — o que o recusou, o que essa coisa espera, o que o projeto exige em vez disso — então desatribua para que outro ator possa completar a entrega. Restaure qualquer estado local que você alterou tentando.

   Um bloqueador que vem de duas regras de projeto se contradizendo merece sua própria issue. Ele atingirá a próxima tarefa, e a seguinte, e cada execução o rediagnosticará do zero. Uma descoberta registrada transforma um imposto recorrente em uma decisão que alguém pode tomar uma vez.

7. Mescle apenas a cabeça do PR revisada após sua CI exigida estar verde, publique quaisquer tags de versão, então close. Renove a reivindicação imediatamente antes de mesclar, exija cabeça revisada/base == cabeça CI/base CI == cabeça/base atual, vincule a mesclagem ao SHA da cabeça revisada e recuse se algum lado moveu. Use a estratégia de mesclagem configurada; um merge commit preserva o limite do branch e a ancestralidade do PR, enquanto squash e rebase descartam deliberadamente essa informação. Recupere o SHA entregue após a mesclagem e verifique se ele tem exatamente a base revisada e a cabeça revisada como seus pais; não afirme preservação de topologia a partir de um sinalizador de comando sozinho. Uma fila de mesclagem é elegível apenas quando seu método configurado garante essa mesma topologia. Se o projeto exigir CI no SHA exato entregue, aguarde esse portão pós-mesclagem.

Trabalhando em um repositório — o fluxo padrão

As regras do repositório vencem, sempre. Leia suas instruções de agente (AGENTS.md, CLAUDE.md ou equivalente) antes de qualquer outra coisa e siga-as. O que se segue é o fallback para um repositório que não prescreve nada, e um piso para um que prescreve apenas parte disso — nunca um padrão concorrente.

O fallback mais antigo — use o histórico de commits como a convenção — não chega tão longe, e vale a pena dizer por quê. Um git log informa como as mensagens de commit são escritas. Ele não pode informar se dois agentes podem compartilhar um checkout, ou se um branch verificado na hora anterior ainda é válido depois que outra pessoa mesclou. Essas respostas decidem se o trabalho paralelo se corrompe, então esta skill as fornece em vez de deixá-las para um domínio que não tem razão para saber.

1. Nunca trabalhe na árvore base. Para um desenvolvedor, o branch padrão é somente leitura: sem edições, sem commits. Verifique antes da primeira alteração em vez de assumir:

git branch --show-current   # main / master -> pare, crie um branch primeiro

Se você descobrir que já fez commit no branch base e NÃO enviou, mova os commits para um branch e redefina. Se já enviou, não faça force push — reverta e refaça corretamente.