oh-my-issues

Transforme uma lista de pendências de issues em um roteiro. Issues são dados de sintomas, não unidades de trabalho — a unidade de trabalho é o defeito arquitetural que as produz. O estado final é open issues == open plans, 1:1.

Princípio central

Pare de fechar issues uma a uma. Agrupe sintomas que compartilham uma única correção arquitetural em um cluster, dê ao cluster um lar canônico (uma issue-mestra de plano + um documento de design plans/0X-*.md), feche cada filho com um redirecionamento padronizado e envie um PR por cluster que feche todos os filhos atomicamente. Novos bugs recebidos são anexados ao mestre correspondente como um comentário "Round N", não abertos como novas issues rastreadas.

Isso se compõe de três maneiras: correções arquiteturais aposentam famílias inteiras de sintomas, a matriz de testes do plano institucionaliza a prevenção em CI, e a triagem padronizada torna o fluxo residual barato.

Quando usar

• O repositório tem mais de 20 issues abertas e muitas parecem duplicadas ou sintomas específicos da plataforma do mesmo defeito.
• O usuário pede para "triar", "consolidar", "agrupar", "deduplicar", "juntar" ou "criar um plano a partir da" lista de issues.
• Um novo bug é aberto e o usuário quer saber se ele pertence a um trabalho existente.
• O usuário quer enviar um PR focado que resolva um cluster de issues relacionadas.

Quando NÃO usar

• Menos de ~15 issues abertas: apenas feche-as.
• Issues são genuinamente independentes (sem causas raiz compartilhadas): uma correção por issue está correta.
• O repositório não tem disciplina de plans/ e o usuário não quer introduzir uma — proponha primeiro, não imponha.

Três modos

Modo 1: Passagem de cluster (redução inicial)

Use quando a lista de pendências nunca foi consolidada. Objetivo: ir de N issues para N_planos mestres em uma única operação.

1. Leia tudo na íntegra. Busque o corpo de cada issue aberta e sua thread de comentários — não apenas os títulos. O agrupamento superficial falha sem o texto completo, e passos de reprodução, duplicatas vinculadas e saída de diagnóstico geralmente vivem em comentários, em vez do corpo original. Veja "Primitivas do GitHub CLI" abaixo para a listagem paginada correta + busca de comentários por issue (uma única chamada gh issue list não retorna corpos de comentários).
2. Agrupe por causa raiz, não por superfície. A pergunta de agrupamento é uma mudança arquitetural aposentaria todas estas? — não estas mencionam a mesma palavra?. "Windows" é uma superfície; "contrato de spawn violado por shells hospedeiros" é uma causa raiz. Duas issues com superfícies diferentes podem compartilhar um cluster (por exemplo, um vazamento de variável de ambiente em dois caminhos de código diferentes compartilhando um único limite de isolamento de ambiente ausente).
3. Nomeie cada cluster como um problema arquitetural. Formato do título: [plan-XX] <Architectural Defect> — <one-line scope>. Exemplo: [plan-02] Spawn-Contract Templating — canonical ${CLAUDE_PLUGIN_ROOT} resolution across all hosts. O título deve implicar uma correção, não um tópico.
4. Abra uma issue mestra por cluster com um corpo que liste: o defeito arquitetural, os filhos (por número da issue), a sequência de correção e uma matriz de testes obrigatória (host × IDE × shell, etc.) que previna regressão.
5. Espelhe cada mestre como plans/0X-<slug>.md no repositório. A issue é o rastreador público; o documento é o design. Eles se referenciam.
6. Feche cada filho com o comentário de redirecionamento padronizado (veja abaixo) e declare not planned.
7. Verifique o estado final: gh issue list --state open retorna exatamente os mestres e nada mais.

Forma alvo para ~100 issues: 4–8 mestres. Mais de 10 significa que você está agrupando por superfície; menos de 3 significa que os clusters são muito amplos para serem enviados como um PR cada.

Modo 2: Triagem (novo bug recebido, estado estável)

Use quando uma nova issue é aberta após a consolidação estar em vigor. Objetivo: nunca deixar a lista de issues se acumular novamente.

1. Leia o corpo da nova issue na íntegra.
2. Padrão-combine o sintoma com os mestres de plano existentes. Para cada mestre aberto, pergunte: a correção descrita aqui também corrigiria este novo bug? Se sim → pertence a esse plano.
3. Se existir uma correspondência, poste um comentário "Round N" no mestre que:
   • Nomeia o novo filho por número
   • Descreve o sintoma em uma linha
   • Esboça a correção concreta (1–3 linhas, por exemplo, "guardar com case "$_SH" in /*.exe|"") _SH=bash ;; esac")
   • Adiciona qualquer nova célula da matriz de testes que o bug expõe
4. Feche o filho com o comentário de redirecionamento padronizado, not planned.
5. Se não houver correspondência e o bug for genuinamente novo: abra um novo mestre de plano + plans/0X-*.md. Resista a isso. A maioria dos bugs são filhos de planos existentes.

Modo 3: Pacote (envie o cluster)

…