Workflow para corrigir issues reportadas em promovaweb/setupvibe.
Plataforma
Esta é a versão Claude Code da skill.
- Use
Read,Grep,EditeBashpara investigar, corrigir e validar. - Mantenha esta skill funcionalmente alinhada com
.codex/skills/fix-issue.
Invocação
/fix-issue <número>
/fix-issue <número> comment
/fix-issue 15— investiga e corrige a issue/fix-issue 15 comment— após a correção, posta comentário na issue pedindo que o reporter teste
Fase 1: Leitura e Diagnóstico
- Leia a issue no GitHub:
gh issue view <número> --repo promovaweb/setupvibe
-
Anote o autor da issue (campo
author:) — será usado no comentário final. -
Identifique o(s) arquivo(s) afetado(s). Os candidatos principais são:
| Arquivo | Quando investigar |
|---|---|
desktop.sh |
Erro em macOS ou Linux desktop |
server.sh |
Erro em servidor Linux |
conf/zshrc-*.zsh |
Problema de PATH, alias ou shell |
conf/tmux-*.conf |
Problema com tmux ou plugins |
docs/ |
Documentação incorreta ou ausente |
- Leia as seções relevantes dos scripts com Read ou Grep antes de propor qualquer mudança. Nunca modifique código que não foi lido.
Fase 2: Criar a Branch
Antes de qualquer edição, crie e mude para a branch de correção:
git checkout -b fix/issue-<número>
Exemplos: fix/issue-15, fix/issue-12.
Fase 3: Identificação da Causa Raiz
Antes de editar, responda:
- Qual linha ou bloco exato causa o problema?
- É um problema de PATH, de permissão, de pipe quebrado, de ordem de execução ou de lógica condicional?
- A correção afeta macOS, Linux ou ambos? Cada OS tem bloco separado nos scripts (
if $IS_MACOS; then ... else ... fi).
Padrões de bug recorrentes no SetupVibe
| Padrão | Sintoma | Correção típica |
|---|---|---|
Pipe quebra user_do |
Parte do comando roda como root | Envolver em user_do bash -c "..." |
$HOME errado em sudo |
Arquivo criado em /root |
Usar $REAL_HOME em vez de $HOME |
mv com CWD errado |
Arquivo não chega ao destino | Usar --install-dir ou path absoluto |
| PATH não disponível em sudo | Comando não encontrado após instalar | Incluir export PATH=...:$PATH dentro do bash -c |
TMPDIR com noexec |
Compilação falha em /tmp |
Usar mkdir -p "$HOME/.tmp"; export TMPDIR="$HOME/.tmp" |
eval "$(tool init -)" ausente |
Shims não disponíveis | Adicionar init antes do uso da ferramenta |
.bashrc não atualizado |
Ferramenta sumiu após nova sessão bash | Adicionar export PATH ao .bashrc também |
Fase 4: Aplicar a Correção
- Edite apenas o(s) arquivo(s) afetado(s) com a ferramenta Edit.
- Respeite o bloco OS correto (
IS_MACOSvselsepara Linux). - Siga os padrões de
user_doesys_dojá estabelecidos no script. - Não adicione tratamento de erro para cenários impossíveis — confie nas garantias do script.
- Se a correção exigir mudança nos zshrc, aplique nos três arquivos relevantes:
conf/zshrc-macos.zshconf/zshrc-linux.zshconf/zshrc-server.zsh(apenas se o problema afeta o server)
Fase 5: Validação
Após editar, confirme:
- O bloco editado está sintaticamente correto (pipes, aspas, escape de variáveis).
-
$REAL_HOMEé usado onde o contexto é sudo. - Comandos dentro de
user_do bash -c "..."escapam variáveis corretamente (\$HOMEvs$REAL_HOME). - A correção não quebra o fluxo do OS oposto.
Fase 6: Commit e Push da Branch
Após validar, faça commit e suba a branch:
git add <arquivos alterados>
git commit -m "fix: <descrição curta da correção> (closes #<número>)"
git push -u origin fix/issue-<número>
Fase 7: Notificação de Conclusão
Quando o código estiver pronto, informe o usuário com este modelo:
Correção aplicada — Issue #<número>
Branch: fix/issue-<número>
Causa raiz: <descrição objetiva em 1-2 linhas>
Arquivos alterados:
| Arquivo | O que mudou |
|---|---|
arquivo.sh |
Descrição da mudança |
Pronto para revisão. Para postar o comentário na issue e avisar o reporter, execute:
/fix-issue <número> comment
Fase 8: Comentário na Issue (argumento comment)
Quando invocado com o argumento comment, poste um comentário na issue via gh com o seguinte conteúdo, adaptando o script afetado (desktop.sh ou server.sh) e a edição:
Para desktop.sh
gh issue comment <número> --repo promovaweb/setupvibe --body "$(cat <<'EOF'
Olá @<autor>! 👋
Identificamos e corrigimos o problema relatado. A correção está disponível na branch `fix/issue-<número>` para testes.
Para testar, execute o comando abaixo no terminal:
**macOS:**
\`\`\`bash
curl -sSL https://raw.githubusercontent.com/promovaweb/setupvibe/fix/issue-<número>/desktop.sh | bash
\`\`\`
**Linux Desktop:**
\`\`\`bash
curl -sSL https://raw.githubusercontent.com/promovaweb/setupvibe/fix/issue-<número>/desktop.sh | bash
\`\`\`
Se o problema for resolvido, confirme aqui nos comentários. Caso contrário, descreva o erro que ainda aparece.
Obrigado pelo report! 🙏
EOF
)"
Para server.sh
gh issue comment <número> --repo promovaweb/setupvibe --body "$(cat <<'EOF'
Olá @<autor>! 👋
Identificamos e corrigimos o problema relatado. A correção está disponível na branch `fix/issue-<número>` para testes.
Para testar, execute o comando abaixo no terminal:
\`\`\`bash
curl -sSL https://raw.githubusercontent.com/promovaweb/setupvibe/fix/issue-<número>/server.sh | bash
\`\`\`
Se o problema for resolvido, confirme aqui nos comentários. Caso contrário, descreva o erro que ainda aparece.
Obrigado pelo report! 🙏
EOF
)"
Substitua <autor> pelo login do usuário que abriu a issue (campo author: lido na Fase 1) e <número> pelo número da issue.
Regra Obrigatória — Markdown
Ao criar ou modificar qualquer arquivo .md, você DEVE invocar a skill /markdown-format antes de concluir a tarefa. As regras de formatação estão em MARKDOWN.md. Esta regra é inegociável e se aplica a qualquer skill, independente do seu escopo.