> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synkrony.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolução Automática de Issues do Sentry

> Triagem inteligente com IA, correção autônoma via Kanbino e limpeza automática de backlog para issues do Sentry

# Resolução Automática de Issues do Sentry

A **Resolução Automática de Issues do Sentry** evolui a integração entre Sentry e Synkrony para fechar todo o ciclo de incidentes — da detecção em produção até o Pull Request pronto para review e o encerramento automático da issue no Sentry.

Em vez de apenas transformar erros em cards no backlog, o Synkrony permite **avaliar cada ocorrência com IA**, **disparar correções automáticas com o Kanbino** (de forma assistida ou 100% autônoma), **sincronizar o fechamento com o merge do Pull Request** e **limpar automaticamente tarefas antigas do backlog**.

> Para habilitar a integração com Sentry no seu workspace, acesse **Configurações → Catálogo de integrações**. Caso ela ainda apareça como **Em breve**, entre em contato com o time comercial ou suporte.

***

## Como Funciona

A resolução automática combina triagem inteligente com IA, geração de Pull Requests pelo Kanbino e sincronização automática com o Sentry em um fluxo contínuo:

**1. Captura da ocorrência no Synkrony**

Quando uma nova issue ou alerta é disparado no Sentry (ou vinculado diretamente pela interface do Sentry), o Synkrony cria ou conecta a tarefa no projeto mapeado com título, resumo e stack trace — e já pode atribuí-la à sprint atual.

**2. Coleta de evidências e código relacionado**

Antes da classificação, o Synkrony busca o evento mais recente na API do Sentry (stack trace priorizando frames internos `in_app`, breadcrumbs relevantes, request e runtime) e lê os trechos de código-fonte apontados pelo erro no repositório GitHub do projeto, ocultando atribuições sensíveis (veja a quantidade de arquivos e o recorte na tabela **Limites Técnicos da Análise**).

**3. Triagem Inteligente com IA e Guardrails**

O modelo escolhido (**Jev (rápido)** ou **Kanbino (análise aprofundada)**) avalia a ocorrência de forma leve, sem iniciar um ambiente de execução de código, enquanto guardrails de segurança verificam se o erro toca áreas críticas. A tarefa recebe então o diagnóstico completo e o veredicto: **Elegível para Auto-Fix**, **Análise Manual** ou **Ignorado (Ruído)**.

**4. Auto-correção via Kanbino e Pull Request**

Se a ocorrência for **Elegível para Auto-Fix** e a auto-correção estiver habilitada, o Kanbino analisa a codebase, implementa a correção em uma branch isolada e abre o Pull Request no GitHub — aguardando sua aprovação do plano no modo assistido ou seguindo direto no modo **Execução 100% autônoma**.

**5. Fechamento sincronizado e limpeza de backlog**

Quando o Pull Request é mesclado (ou a tarefa é movida para `Done`), a issue correspondente é marcada automaticamente como `resolved` no Sentry. Em paralelo, uma rotina diária monitora tarefas antigas paradas no `Backlog` além do prazo configurado para resolver e encerrar ocorrências obsoletas.

***

## Classificação e Critérios de Elegibilidade

Toda issue avaliada pela **Triagem Inteligente com IA** recebe um veredicto estruturado, visível tanto no card da tarefa quanto em um comentário automático postado pelo agente **Sentry**.

### Veredictos Possíveis

| Veredicto | Significado | Próximo Passo |
| - | - | - |
| **Elegível para Auto-Fix** | Bug de código claro, reproduzível e seguro para tentativa de correção em branch isolada | Dispara o Kanbino automaticamente (se o auto-fix estiver ativado) |
| **Análise Manual** | Evidência insuficiente, escopo amplo, confiança abaixo do limiar ou violação de guardrail | Permanece no backlog/sprint para investigação humana |
| **Ignorado (Ruído)** | Evento transitório, falha externa benigna, atividade de bot ou ruído de cliente | Registrado na tarefa sem acionar execução de IA |

### Categorias Técnicas Identificadas

O classificador categoriza cada ocorrência para facilitar a triagem do time:

* `Null Pointer` (referências nulas ou indefinidas)
* `Tipo / Sintaxe` (incompatibilidade de tipos, erro de sintaxe, método inexistente)
* `Rede / API` (falhas de rede, timeouts, erros HTTP 5xx ou serviços externos)
* `Banco de Dados` (erros de ORM, SQL ou restrições de banco)
* `Validação` (argumentos ausentes ou payloads inválidos)
* `Outro` (demais casos)

### Regras para Disparar Auto-Fix

Para que uma tarefa seja considerada **Elegível para Auto-Fix** e acione o Kanbino, **todos** os critérios abaixo precisam ser atendidos simultaneamente:

1. A ação recomendada pelo classificador é `auto_fix`
2. Probabilidade de **Bug de Código** maior ou igual a **70%**
3. Probabilidade de **Seguro p/ Auto-Fix** maior ou igual a **70%**
4. **Confiança do modelo** igual ou superior ao percentual configurado em **Confiança mínima para auto-fix** (consulte o padrão e a faixa permitida na tabela **Limites Técnicos da Análise**)
5. **Nenhuma violação de guardrail** detectada

### Guardrails de Segurança

Se o título do erro, `culprit`, tipo/mensagem de exceção ou stack trace contiver referências a áreas sensíveis, o Synkrony **força a retenção para Análise Manual** (definindo a segurança para `0%`) e exibe o aviso **Violação de Guardrail** na tarefa.

Os padrões protegidos pelos guardrails incluem:

* Migrações de banco de dados (`db/migrate/`)
* Módulos financeiros nos caminhos `app/controllers/financial/` e `app/services/financial/` (erros em código financeiro fora desses diretórios não acionam esse guardrail de caminho)
* Integrações de pagamento (`stripe`)
* Credenciais, chaves e segredos (`credentials`, `secrets.yml`, `secrets.yaml`, `master.key`)
* Fluxos de autenticação e acesso (`auth`, `password`, `session`)

> [!WARNING]
>
> Os guardrails existem para impedir modificações autônomas em fluxos críticos de segurança, faturamento ou estrutura de banco de dados. Nesses casos, um desenvolvedor deve revisar e conduzir a correção.

***

## Modos de Auto-Correção: Assistido vs. 100% Autônomo

Você escolhe o nível de autonomia do Kanbino nas configurações da integração com o Sentry:

| Modo | Como Funciona | Quando Usar |
| - | - | - |
| **Apenas Triagem** | Classifica cada nova issue e publica diagnóstico + métricas na tarefa, sem iniciar execução de código | Para ganhar visibilidade e validar a precisão do classificador antes de automatizar PRs |
| **Auto-Fix Assistido** | Quando elegível, o Kanbino cria o plano de correção (e eventuais perguntas de esclarecimento) e aguarda sua aprovação humana no Modo IA antes de editar código | Ideal para times que querem acelerar o diagnóstico e plano, mas preferem revisar a estratégia antes da implementação |
| **Execução 100% Autônoma** | Quando elegível, o Kanbino gera o plano, aprova automaticamente sem pausa para confirmação, implementa o código, executa validações disponíveis e abre o Pull Request direto no GitHub | Ideal para bugs bem isolados (ex.: `nil_pointer`, validações simples) quando você quer chegar no GitHub já com o PR pronto para code review |

> [!NOTE]
>
> **Controle humano preservado:** mesmo com a **Execução 100% autônoma** ativada, o Kanbino trabalha exclusivamente em uma branch isolada e abre um Pull Request. Ele **nunca faz merge nem deploy em produção** — seu CI e a revisão humana do PR continuam sendo obrigatórios.

***

## Sincronização de Resolução e Limpeza Automática de Backlog

### 1. Sincronização Bidirecional (`Done ↔ Resolved`)

Para fechar o ciclo ponta a ponta sem atualizações manuais duplicadas:

* **Resolver issue no Sentry ao mover tasks para Done:** sempre que a tarefa vinculada avança para uma coluna de conclusão (`Done`) — seja porque você moveu o card manualmente ou porque o Pull Request aberto pelo Kanbino foi **mesclado no GitHub** — o Synkrony marca automaticamente a issue correspondente como `resolved` no Sentry.
* **Marcar task como Done quando a issue for resolvida:** quando alguém resolve a issue diretamente no Sentry, o webhook atualiza a tarefa vinculada no Synkrony para `Done`.

> [!TIP]
>
> Se você ativou a **Execução 100% autônoma**, certifique-se de ativar também **Resolver issue no Sentry ao mover tasks para Done** e manter o mapeamento de status `Done` no GitHub configurado. Assim, ao fazer merge do PR, tanto a tarefa quanto a issue no Sentry são fechadas juntas.

### 2. Limpeza Automática de Tarefas no Backlog

Equipes que recebem alto volume de alertas frequentemente acumulam ocorrências antigas ou irrelevantes no backlog. A opção **Limpeza automática de tarefas no backlog** automatiza essa higiene:

* **Frequência:** executada diariamente em segundo plano (conforme janela definida na tabela **Limites Técnicos da Análise**).
* **Critério:** seleciona tarefas vinculadas a issues do Sentry que ainda estejam em status de **Backlog** e tenham sido criadas há mais dias do que o prazo configurado (veja o padrão e a faixa aceita em **Limites Técnicos da Análise**).
* **Ação executada:**
  1. Resolve as issues correspondentes em lote no Sentry (respeitando o tamanho máximo de lote da tabela **Limites Técnicos da Análise**).
  2. Publica um comentário automático do sistema na tarefa explicando o encerramento pela política de limpeza após o prazo configurado.
  3. Move a tarefa para o status `Done` do workspace.

***

## Pré-requisitos

Antes de ativar a resolução automática, confira o checklist abaixo:

1. **Integração Sentry habilitada e conectada** no workspace.
2. **Projetos vinculados** entre Sentry e Synkrony (mapeando qual projeto externo envia ocorrências para qual projeto interno).
3. **Provedor de triagem disponível** no workspace (**Jev** ou **Kanbino** com chave compatível da Anthropic ou Z.ai).
4. **Para contexto de código e Auto-Fix via Kanbino:**
   * **GitHub App** conectado em **Configurações → GitHub** ([ver guia](https://docs.synkrony.ai/github-integration.md));
   * **Repositório do GitHub** preenchido nas configurações de cada projeto do Synkrony que receberá auto-correção;
   * Execuções disponíveis no plano de **Modo IA** ([ver planos](https://docs.synkrony.ai/planos.md)).

> [!WARNING]
>
> Se uma issue for classificada como **Elegível para Auto-Fix**, mas o projeto no Synkrony não tiver um repositório GitHub configurado, o Kanbino não será iniciado e um comentário de aviso explicando o motivo será adicionado à tarefa.

***

## Configuração Passo a Passo

**1. Conecte e vincule seus projetos do Sentry**

Acesse **Configurações → Catálogo de integrações → Sentry**. Caso sua empresa utilize mais de uma organização no Sentry, é possível conectar múltiplas integrações usando **+ Nova integração** e alternar entre elas no topo da página.

Na seção **Projetos vinculados**, associe cada projeto interno do Synkrony aos projetos correspondentes do Sentry.

**2. Configure as automações de fluxo**

Na seção **Automações**, habilite conforme o processo do seu time:

* **Criar task automaticamente:** gera a tarefa no Synkrony quando uma issue ou alert chega do Sentry.
* **Marcar task como Done quando a issue for resolvida:** sincroniza resoluções feitas diretamente no Sentry.
* **Resolver issue no Sentry ao mover tasks para Done:** fecha a issue no Sentry quando a task é concluída ou seu PR é mesclado.
* **Limpeza automática de tarefas no backlog:** ative e defina o prazo em dias no backlog para resolver e encerrar ocorrências antigas paradas no backlog.
* **Atribuir à sprint atual:** coloca novas tarefas já na sprint vigente (quando sprints estiverem habilitadas no workspace).

**3. Configure a Triagem Inteligente com IA**

Na seção **Triagem Inteligente com IA**, ajuste os parâmetros:

1. **Modelo de classificação:** escolha entre **Jev (rápido)** ou **Kanbino (análise aprofundada)**.
2. **Ativar triagem automática:** ligue para classificar automaticamente cada nova issue recebida ou vinculada.
3. **Disparar auto-correção via Kanbino:** ligue se quiser que ocorrências elegíveis acionem o Kanbino automaticamente.
4. **Execução 100% autônoma (sem aprovação de plano):** ligue caso deseje que o Kanbino implemente e abra o PR diretamente sem aguardar aprovação manual do plano.
5. **Confiança mínima para auto-fix:** defina o percentual mínimo desejado conforme a faixa descrita em **Limites Técnicos da Análise**.

**4. Salve e valide em um projeto piloto**

Clique em **Salvar** na barra inferior de confirmação e envie uma issue de teste (ou aguarde uma ocorrência real) em um projeto piloto com repositório GitHub vinculado.

Comece validando com apenas a triagem ou o **Auto-Fix Assistido** antes de liberar a **Execução 100% autônoma** para todos os projetos.

***

## Como Acompanhar no Dia a Dia

### No Quadro Kanban

* Tarefas originadas do Sentry exibem o **ícone rosa do Sentry** no card.
* Na barra de ferramentas do Kanban, o menu de integrações (ícone de quebra-cabeça) permite filtrar rapidamente:
  * **Todas as tarefas**
  * **Filtrar tarefas do sentry** (exibe apenas incidentes do Sentry)
  * **Ocultar tarefas do sentry**

### Dentro da Tarefa (`Conexões`)

Ao abrir uma tarefa vinculada ao Sentry, a seção **Conexões** mostra:

1. **Card da Issue do Sentry:** código identificador (`shortId`), tempo desde a última ocorrência, quantidade de eventos, estado (`resolvido` ou `não resolvido`) e link direto para abrir a issue no Sentry.
2. **Card de Avaliação (`Avaliação do Jev` ou `Avaliação do Kanbino`):** inicia recolhido mostrando categoria, veredicto e percentual de confiança. Ao clicar para expandir, exibe:
   * **Confiança** (%)
   * **Bug de Código** (%)
   * **Seguro p/ Auto-Fix** (%)
   * **Violação de Guardrail** (quando aplicável, em vermelho)
   * **Diagnóstico** técnico resumido
   * Data e hora da triagem

### Nos Comentários e Execução IA

* Um comentário formatado pelo agente **Sentry** registra o resultado completo da triagem na linha do tempo da tarefa.
* Se o auto-fix for acionado, um segundo comentário informa se foi iniciado em modo **Autônomo** ou **Assistido**, e o status da tarefa avança automaticamente do backlog para andamento assim que o planejamento começa.
* No modo assistido, você pode abrir o **Modo IA** da tarefa para responder perguntas, ajustar ou confirmar o plano; no modo autônomo, o PR aparecerá vinculado na tarefa assim que concluído.

***

## Custos, Créditos e Limites Técnicos

### Consumo de Créditos de IA

| Etapa | Consome Execução do Modo IA? | Observação |
| - | - | - |
| **Triagem Inteligente (Jev ou Kanbino)** | **Não** | Roda sem iniciar ambiente de execução de código e não desconta da cota mensal de execuções |
| **Auto-Fix via Kanbino** | **Sim (1 execução)** | Só consome crédito quando a issue é elegível, o auto-fix está ativo e uma execução do Kanbino é iniciada |
| **Limpeza Automática de Backlog** | **Não** | Apenas sincroniza resolução via API do Sentry e atualiza o status no Synkrony |

Consulte os limites mensais de execuções do Modo IA na página de [Planos e Preços](https://docs.synkrony.ai/planos.md).

### Limites Técnicos da Análise

| Parâmetro | Limite |
| - | - |
| **Stack trace enviado à triagem** | Até 10 frames (priorizando frames `in_app`) |
| **Breadcrumbs analisados** | Até 10 breadcrumbs relevantes mais recentes |
| **Arquivos de código-fonte do GitHub** | Até 3 arquivos por triagem (máx. 250 KB cada, ±20 linhas por frame) |
| **Confiança mínima para auto-fix** | Configurável entre 50% e 100% (padrão 85%) |
| **Prazo de limpeza de backlog** | Configurável entre 1 e 999 dias (padrão 14 dias) |
| **Frequência e lote da limpeza de backlog** | Diária (01:00), em lotes de até 50 issues no Sentry |

***

## Boas Práticas

* **Comece usando o padrão de confiança mínima:** evite baixar demais o limiar logo no início; reduza gradualmente apenas se notar bons bugs sendo retidos para análise manual.
* **Filtre alertas ruidosos no próprio Sentry:** regras de *Issue Alert* focadas em `production` e erros acionáveis evitam triagens desnecessárias.
* **Mantenha os repositórios e branches base atualizados:** confira se cada projeto tem o repositório GitHub conectado e a branch base correta (`main`, `master`, etc.), pois tanto o contexto de código quanto a criação do PR dependem disso.
* **Combine Auto-Fix com CI e Code Review:** deixe testes automatizados e linters configurados no repositório para que o Kanbino valide a correção antes mesmo de você revisar o PR.
* **Ative o fechamento bidirecional:** ligar **Resolver issue no Sentry ao mover tasks para Done** garante que nenhum erro corrigido via PR continue aberto no Sentry.

***

## ❓ FAQ

**A triagem automática cria um ambiente/pod de execução para cada erro do Sentry?**
Não. Tanto o **Jev (rápido)** quanto o **Kanbino (análise aprofundada)** executam a triagem de forma leve e direta, sem iniciar ambiente de execução de código. O ambiente completo do Kanbino só é iniciado se a issue for considerada elegível e o auto-fix estiver habilitado.

**Qual a diferença entre "Jev (rápido)" e "Kanbino (análise aprofundada)" na triagem?**
O **Jev** é otimizado para classificação rápida e econômica de grandes volumes de ocorrências. O **Kanbino (análise aprofundada)** utiliza o modelo de linguagem diretamente para gerar um diagnóstico mais detalhado — ambos respeitam os mesmos guardrails de segurança e critérios de confiança.

**O Kanbino pode fazer merge automático de uma correção em produção?**
Não. Mesmo com **Execução 100% autônoma (sem aprovação de plano)** ativada, o Kanbino apenas cria uma branch isolada, implementa a correção e abre um Pull Request. O merge e o deploy continuam sob controle da sua equipe no GitHub.

**Por que uma issue simples foi marcada como "Análise Manual"?**
Isso ocorre quando pelo menos um dos critérios não é atingido: pontuação de **Bug de Código** ou **Seguro p/ Auto-Fix** abaixo do mínimo exigido, confiança abaixo do limiar configurado (consulte as seções **Regras para Disparar Auto-Fix** e **Limites Técnicos da Análise**), stack trace ausente/ambíguo ou acionamento de algum **guardrail de segurança** (como autenticação, pagamento, caminhos financeiros ou migrações).

**O que acontece se um projeto não tiver repositório GitHub vinculado?**
A tarefa ainda é criada e a triagem ainda pode rodar usando os dados do Sentry, mas o auto-fix é bloqueado automaticamente e um comentário na tarefa avisa que falta configurar o repositório GitHub no projeto.

**A limpeza automática de backlog apaga as tarefas?**
Não. Ela resolve as issues correspondentes no Sentry, adiciona um comentário automático registrando o motivo e move as tarefas do `Backlog` para `Done`, preservando todo o histórico no Synkrony.

**Posso conectar mais de uma organização do Sentry?**
Sim. Na página de configuração da integração Sentry, você pode adicionar múltiplas organizações com **+ Nova integração** e configurar cada uma de forma independente.

***

## Troubleshooting

### A seção "Triagem Inteligente com IA" não aparece na configuração do Sentry

Verifique se a integração com o Sentry está conectada e ativa, e confirme se o workspace possui um provedor de classificação habilitado (plataforma ou chave de API compatível configurada).

### A issue foi marcada como "Elegível para Auto-Fix", mas o Kanbino não iniciou

Verifique os seguintes pontos:

* A opção **Disparar auto-correção via Kanbino** está ativada na integração Sentry;
* O projeto do Synkrony possui um **Repositório do GitHub** configurado;
* A empresa possui o **GitHub App** conectado;
* A tarefa não possuía uma execução do Kanbino já em andamento ou concluída anteriormente;
* O workspace não atingiu o limite mensal de execuções do **Modo IA** ([ver planos](https://docs.synkrony.ai/planos.md)).

### A execução foi marcada com erro ou bloqueio aguardando contexto de IA

Se o workspace exigir contexto de IA prévio do projeto para rodar o Kanbino, verifique nas configurações do projeto se a geração inicial de contexto foi concluída após vincular o repositório GitHub.

### O Pull Request foi mesclado, mas a issue continuou aberta no Sentry

Confira:

1. Se a opção **Resolver issue no Sentry ao mover tasks para Done** está ativada na integração Sentry;
2. Se o seu fluxo no Synkrony possui um status mapeado com tipo `done` para o GitHub ([ver integração GitHub](https://docs.synkrony.ai/github-integration.md));
3. Se o título do PR contém o slug da tarefa (ex.: `[SW-123]`).

### O status da integração exibe "Reconexão necessária"

Isso indica que a autorização OAuth com o Sentry expirou ou a instalação do app foi alterada/removida no Sentry. Clique para reconectar a integração em **Configurações → Catálogo de integrações → Sentry**.

***

## Documentação Relacionada

* [Integração com Sentry](https://docs.synkrony.ai/sentry-integration.md) — Conceitos básicos, alertas do Sentry e mapeamento de projetos
* [Kanbino - Agente de IA](https://docs.synkrony.ai/kanbino.md) — Arquitetura e ciclo de vida do agente que executa as correções
* [Modo AI](https://docs.synkrony.ai/ai-mode.md) — Fluxo de revisão de plano, acompanhamento em tempo real e boas práticas
* [Integração com GitHub](https://docs.synkrony.ai/github-integration.md) — Conexão de repositórios e sincronização de Pull Requests


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.