De issues soltas a pull requests automáticos: a linguagem que faz o Shift agir com precisão

Imagine uma issue aberta no repositório: título razoável, alguma descrição, talvez uma discussão no thread. Agora imagine que um agente autônomo vai executar essa issue — vai ler o contexto, escrever o código, abrir o PR.

A pergunta que importa não é “o agente consegue fazer isso?”. A pergunta é: o agente vai acertar na primeira tentativa, ou vai produzir um PR que não serve?

A qualidade da execução do Shift depende do contexto que ele recebe. O ICM — Interpretable Context Methodology organiza esse contexto no repositório: regras gerais, orientação por área e instruções locais. É por isso que o Shift consegue trabalhar sem depender de um agente especializado para cada pasta.

As Incantations complementam essa base. Elas ajudam a avaliar e preparar cada issue, e indicam quando o Shift deve executá-la. O ICM explica ao agente como navegar e trabalhar no repositório; as Incantations dão forma ao contexto e à intenção de cada tarefa.

Um repositório que responde a feitiços

Na plataforma de dados da CERC, adotamos uma metáfora que não é só estética. Quando chamamos o catálogo de comandos de Incantations e a estrutura que os guarda de Grimoire, estamos dizendo algo sobre como esse sistema deve ser tratado: com respeito, com precisão, com consciência de que a invocação errada tem consequências.

• DataPlatform Shift é o agente autônomo que executa tarefas de engenharia no repositório — ele lê uma issue, entende o escopo, escreve código e abre um pull request.
• Grimoire é o tomo estrutural: a coleção organizada de scripts e automações que dão vida às regras do Shift dentro do repositório.
• Incantations são as invocações — o catálogo oficial e versionável de tudo que pode ser dito ao repositório para produzir um efeito concreto.

O ponto central: as Incantations existem para preparar o caminho antes do Shift executar. Cada label, cada comando, cada transição de estado serve a um propósito: garantir que, quando o agente finalmente rodar, ele terá o contexto mais completo, claro e bem-definido possível.

O ponto que diferencia esse design de um workflow comum é a separação entre o que o sistema sabe sobre si mesmo e o que os humanos podem invocar. As Incantations são essa fronteira.

A distinção que muda tudo: lbl versus cmd

O catálogo hoje expõe exatamente dois flavors de Incantation. Dois não por limitação — por escolha deliberada.

Essa separação carrega uma distinção filosófica importante: estado e intenção não são a mesma coisa, e confundi-los cria sistemas frágeis.

Um label shift:lbl:ready diz ao sistema que a issue foi avaliada e está pronta para o Shift. Um @shift:cmd:resolve diz que eu, humano, estou decidindo disparar a execução agora. O primeiro é uma memória — o segundo é uma vontade.

Ao nomeá-los com flavors distintos, o catálogo torna essa diferença impossível de ignorar.

A anatomia de uma Incantation

Cada Incantation tem uma identidade canônica — a forma completa e inequívoca — e um token operacional — o valor exato que aparece no GitHub.

shift:lbl:needs-context    →  issue aguarda mais contexto para o Shift agir
shift:lbl:blocked          →  escopo fora da jurisdição do Shift
shift:lbl:ready            →  pronta para execução autônoma
shift:lbl:running          →  task criada, execução em andamento

@shift:cmd:resolve         →  disparar execução de uma issue pronta
@shift:cmd:improve-context →  consolidar contexto e reclassificar

São seis tokens. Mas dentro deles vive toda a lógica de preparação e controle de uma plataforma agentic em produção.

Duas camadas de IA, um único fluxo

Antes de entrar nos estados e comandos, vale nomear algo que fica implícito no design: todo o fluxo de Incantations usa dois sistemas de IA com papéis radicalmente diferentes.

Essa separação é intencional. O Gemini filtra, avalia e estrutura — tudo dentro dos workflows do GitHub Actions, sem custo de latência de agente. O Shift executa. As Incantations são a camada que garante que o Shift sempre receba o melhor insumo possível quando finalmente for invocado.

A máquina de estado que alimenta o agente

O que torna o design das Incantations elegante é que ele não é apenas uma lista de comandos — ele define uma máquina de estado explícita. Cada issue está sempre em algum estado Shift, e o agente só recebe uma issue quando ela chegou ao estado ready com contexto suficiente para uma boa execução.

flowchart LR
    A[sem label] -->|issue aberta ou comentario| T[triage passivo]
    T --> NC[needs-context]
    T --> BL[blocked]
    T --> RD[ready]
    NC -->|improve-context| IC[consolida e reclassifica]
    BL -->|improve-context| IC
    RD -->|improve-context| IC
    IC --> T
    RD -->|resolve| RN[running]
    RN -->|PR com closes fechado| A

O fluxo completo existe para uma razão: quando o Shift finalmente executa, o contexto da issue já passou por múltiplas camadas de avaliação e consolidação. Isso não é burocracia — é a diferença entre um PR que acerta e um que precisa de cinco rounds de revisão.

needs-context: a issue ainda não está pronta para o agente

Este é o estado mais frequente para issues novas. O triage passivo avaliou e identificou que faltam elementos para que o Shift possa trabalhar com segurança: contexto técnico suficiente, critério de aceite claro, recorte de escopo definido, caminho de validação explícito.

É um estado honesto. Não diz que a issue é ruim — diz que ela ainda não está completa o suficiente para ser entregue ao agente. Um Shift executando sobre uma issue em needs-context produziria um PR impreciso ou incompleto. A label existe para prevenir exatamente isso.

blocked: fora da jurisdição

shift:lbl:blocked é a fronteira de segurança da plataforma. Quando o triage identifica que o escopo penetra em áreas proibidas — arquivos de CI/CD, configurações de pipeline, estruturas de permissão — ele sinaliza que o Shift não deve atuar ali.

O que torna esse guardrail sofisticado é que ele não é puramente lexical. Citar .github/workflows como exemplo de “o que não fazer” não bloqueia a issue. O que bloqueia é o path aparecer como escopo real de implementação. Quando há ambiguidade, o Gemini — rodando no GitHub Actions — decide semanticamente. Essa distinção entre citação e escopo real é o tipo de nuance que um regex nunca resolveria e que faz a diferença entre um guardrail que protege e um que atrapalha.

ready: a runa de prontidão

shift:lbl:ready é o estado mais valioso do catálogo. Significa que a issue passou em todos os critérios de triage e tem contexto suficiente para uma boa execução do Shift. O agente, quando disparado, terá o insumo necessário para produzir um PR relevante e correto.

Mas ready não significa que o Shift vai rodar — a execução ainda depende de uma invocação humana explícita. O humano mantém o controle de quando disparar, mesmo que o sistema já tenha validado que a issue está pronta.

Um detalhe importante: ready não é um estado pegajoso. Qualquer novo comentário na issue dispara uma nova rodada de triage. Se o comentário trouxer contexto que mude a leitura — por exemplo, expandindo o escopo para uma área proibida — a issue pode ser reclassificada para blocked ou needs-context mesmo depois de ter chegado a ready. A label sempre reflete o que o sistema concluiu na última avaliação.

running: a invocação foi aceita

shift:lbl:running marca que a task foi criada e o Shift está executando. É o estado de trânsito — a issue ainda está viva enquanto o PR não foi vinculado. Quando o PR assume a jurisdição, a label é removida automaticamente.

Os dois comandos: intenções distintas com mecânicas distintas

@shift:cmd:improve-context: o feitiço do contexto

Este comando tem uma função precisa: forçar uma nova consolidação de contexto e disparar um novo ciclo de triage. O objetivo não é produzir um resumo legível para humanos — é alimentar o próximo ciclo de avaliação do Shift com informação mais completa e estruturada, para que o agente tenha insumo melhor na hora de executar.

Quando você comenta @shift:cmd:improve-context em uma issue, dois comentários são publicados em sequência garantida:

Primeiro — o comentário consolidado: o workflow do GitHub Actions lê todo o thread, filtrando comentários de automação para evitar ruído, e usa o Gemini para produzir uma consolidação estruturada com três componentes:

• Resumo do estado atual — o que está claro sobre o pedido e onde ele está travado.
• Fatos-chave do thread — apenas informações que emergiram da discussão e não estavam no body original da issue: nomes de arquivos, jobs, serviços, requisitos específicos levantados nos comentários.
• Blockers em aberto — somente as perguntas que impedem o triage de readiness, não qualquer dúvida geral.

Segundo — o novo [shift-triage]: imediatamente após publicar a consolidação, o sistema dispara uma nova rodada de triage já com esse material como base e publica um novo comentário de classificação. A issue pode sair de needs-context para ready no mesmo ciclo.

O comando aceita contexto adicional. Você pode escrever @shift:cmd:improve-context e continuar no mesmo comentário — ou em linhas abaixo — com informações que quer incluir. O Shift entende que tudo depois do comando é orientação do operador e esse conteúdo entra diretamente na consolidação. Editar um comentário existente também funciona: se o conteúdo final ainda começar com @shift:cmd:improve-context, o ciclo inteiro é reexecutado.

Esse design torna o improve-context o caminho mais eficiente para destravar uma issue parada: em vez de aguardar outro ciclo passivo de triage, você injeta contexto e força a reavaliação imediata. Funciona em qualquer estado de label.

@shift:cmd:resolve: o feitiço da resolução

Este é o único ponto do fluxo em que o Shift — o agente autônomo de engenharia — é finalmente invocado. Tudo o que veio antes (triage pelo Gemini, consolidações de contexto, transições de estado) foi preparação. O resolve é o gatilho que converte contexto validado em execução real.

Para ser aceito, ele exige:

• A issue estar com shift:lbl:ready — não needs-context, não blocked.
• O comentário ser exatamente @shift:cmd:resolve — sem texto adicional antes, durante ou depois. Editar um comentário existente também funciona, desde que o conteúdo final seja exatamente esse.
• Não existir PR já vinculado à issue.
• A issue não estar em shift:lbl:running.

Essas condições não são burocracia. Cada uma elimina uma classe específica de erro:

• A exigência de ready garante que o agente só recebe issues que já passaram pelo crivo do triage — issues com contexto validado.
• A exigência de exatidão elimina invocações acidentais em comentários onde o comando aparece como menção ou exemplo.
• A verificação de PR vinculado previne execuções duplicadas quando um PR já está em andamento mas a label ainda não foi atualizada.
• A verificação de running garante que não há dois agentes trabalhando na mesma issue em paralelo.

Quando todas as condições são atendidas, o Shift prepara o contexto final da issue — filtrando comentários de automação, marcadores internos e invocações anteriores de resolve — e cria a task. A issue recebe shift:lbl:running, e a URL da task é comentada automaticamente para que o time possa acompanhar.

A inteligência passiva: triage sem precisar pedir

Não é só quando um humano comenta que o sistema age. Uma das características mais poderosas das Incantations é que parte substancial da inteligência do Shift roda passivamente, sem invocação explícita.

Toda vez que uma issue é aberta ou um comentário é criado — ou editado —, o triage passivo avalia automaticamente o estado, atualiza a label e publica um novo comentário [shift-triage]. O fluxo é append-only: cada rodada adiciona um comentário novo à thread, nunca sobrescreve os anteriores. Isso preserva o histórico completo de avaliações na própria issue. O sistema mantém também um estado oculto com metadados que persistem entre avaliações, permitindo que cada rodada de triage parta de onde a anterior parou.

Quando uma issue finalmente atinge shift:lbl:ready, o Shift publica automaticamente um comentário com a instrução exata do próximo passo — @shift:cmd:resolve — para que o operador não precise lembrar a sintaxe. Esse helper é marcado internamente e não contamina o contexto enviado ao agente quando a execução começa.

O sistema também limpa automaticamente shift:lbl:running em dois cenários distintos: quando a issue é fechada diretamente no GitHub, e quando um PR que a referencia é aberto com as closing directives corretas (closes #N, fixes #N, resolves #N). No segundo caso, a jurisdição migra para o PR. Em ambos, nenhuma ação humana é necessária além do gesto que já estava sendo feito.

Guardrails: por que o controle é o produto

Uma plataforma agentic que não sabe dizer não é perigosa. As Incantations foram desenhadas com um princípio claro: cada guardrail existe para preservar a confiança no sistema.

Os caminhos possíveis: semântica e fluxos de execução

O design em máquina de estado significa que existem fluxos bem definidos para as situações mais comuns. Cada um tem nome e sequência de passos conhecida:

Caminho 1 — issue pronta e disparo direto

Descrição do fluxo: a issue é aberta com bom contexto, o triage aplica ready, alguém comenta @shift:cmd:resolve, o Shift executa com o contexto que já estava validado, cria a task, marca running, abre o PR e então a jurisdição migra. O caminho feliz — possível porque a issue chegou preparada.

Quando a issue recebe ready

ready é o raro estado de harmonia — significa que o Gemini concluiu que há contexto suficiente, o escopo é bem delimitado e nenhuma área de controle está envolvida. O Shift tem tudo que precisa para executar.

Sinais de readiness:

• Critério de aceite é testável e claro.
• Escopo é contido — modificações em um ou poucos arquivos relacionados.
• Contexto técnico é completo — referências a sistemas, versões, dados de exemplo inclusos.
• Nenhuma pergunta pendente no thread.
• Path de implementação não toca áreas bloqueadas.

Exemplo: “Adicionar cache em memória para queries frequentes no serviço de ingestão. Use Redis com TTL de 5min. Casos de teste: queries para top 100 receíveis, queries para composição por período. Validar em test/ingest.ts. Nenhuma mudança em CI/CD.” Isso é ready imediato.

Caminho 2 — issue incompleta

Descrição do fluxo: o triage aplica needs-context. Discussão acontece no thread. Alguém comenta @shift:cmd:improve-context com o contexto acumulado. O Shift consolida e reclassifica. Se virar ready, o agente já tem o insumo necessário para executar com assertividade.

Quando a issue recebe needs-context

O Gemini procura elementos que indicam incompletude não superficial:

• Falta critério de aceite claro — a issue diz o que deve ser feito, mas não deixa explícito como reconhecer que está feito. O agente precisa dessa linha de chegada.
• Escopo vago ou aberto — “melhorar a performance” sem indicar onde, qual métrica, qual é o target. O Shift executaria, mas provavelmente não na direção certa.
• Contexto técnico insuficiente — referências a sistemas, jobs ou serviços são feitas sem indicar onde encontrá-los, qual versão, qual é o comportamento esperado.
• Perguntas em aberto no thread — alguém comentou com dúvida técnica legítima que ainda não foi respondida. Significa que até os humanos ainda estão entendendo o escopo.

Exemplo: “Adicionar validação no job de ingestão” sem dizer qual job, qual validação, qual erro que justifica a mudança. O Gemini vai pedir que isso seja claro antes de marcar como ready.

Caminho 3 — bloqueio estrutural

Descrição do fluxo: o triage detecta escopo proibido, aplica blocked. O time precisa recortar a issue — separar escopos, criar sub-issues — antes de tentar de novo. improve-context pode ajudar a consolidar o novo recorte antes da próxima avaliação.

Quando a issue recebe blocked

blocked é acionado quando o caminho de implementação atravessa áreas sob jurisdição de controle ou segurança da plataforma. O triage detecta:

• Modificação em .github/workflows, .github/actions, ou scripts de CI/CD — isso não é meramente uma referência. É o caminho que o PR ia percorrer.
• Mudanças em arquivos de configuração ou permissões — .env, declarações de secrets, modificações de RBAC.
• Estruturas críticas para auditoria — logs de auditoria, mecanismos de verificação, rastreamento de compliance.

O detalhe importante: nomear o arquivo não bloqueia a issue. Se você escrever “não modificar .github/workflows”, isso é contexto, não bloqueio. O que bloqueia é o triage concluir que a implementação vai modificar aquele arquivo. Essa é a nuance que um regex nunca capturaria — e a razão pela qual o Gemini avaliza a decisão.

Exemplo: “Automatizar deploy em staging” pode ou não ser bloqueado. Se a solução é montar um novo workflow no .github/workflows, é bloqueado. Se é adicionar um novo job em um workflow existente ainda sob review de segurança, também é bloqueado. Se é configurar um trigger em um workflow já aprovado, pode virar ready.

O que o Grimório representa para a engenharia de plataforma

É tentador ver as Incantations como um conjunto de labels e comandos do GitHub. Mas o que elas realmente representam é algo mais ambicioso: uma camada de preparação que faz a diferença entre um agente que acerta e um que erra.

A premissa do sistema é simples mas poderosa: um agente autônomo é tão bom quanto o contexto que recebe. Ao criar uma nomenclatura canônica, ao separar estado de intenção em flavors distintos, ao documentar cada transição de estado com precisão, a CERC criou uma superfície de controle deliberada — um conjunto de pontos onde o humano pode melhorar iterativamente o contexto que o Shift vai consumir.

Qualquer engenheiro que abre uma issue e vê shift:lbl:needs-context sabe exatamente o que falta para o Shift poder executar bem. Qualquer um que vê shift:lbl:ready sabe que o agente tem o que precisa para produzir um bom PR. Ninguém precisa perguntar “isso está pronto para o Shift?” — o sistema responde com as labels.

Isso é, no fim, o que diferencia uma plataforma agentic madura de uma coleção de scripts bem-intencionados: rastreabilidade como cidadã de primeira classe, controle que escala sem depender de conhecimento tribal, e uma gramática compartilhada que garante que o agente sempre receba o melhor contexto possível.

O que vem a seguir

O catálogo tem dois flavors hoje, e as Incantations vivem inteiramente no mundo das issues. Mas o próximo passo natural já está no horizonte: estender o sistema para pull requests.

A lógica é a mesma — estados que dizem o que é verdade, comandos que expressam intenção — só que aplicada ao ciclo de revisão do PR. Um PR que passou por revisão automatizada, que consolidou feedback de múltiplos reviewers, que já tem contexto estruturado para o Shift re-executar uma correção: esse é o objetivo.

A separação entre lbl e cmd foi desenhada para crescer sem reescrever o contrato atual. Quando os comandos de PR chegarem, vão se encaixar na mesma gramática — e qualquer engenheiro que já usa as Incantations de issue vai reconhecer a sintaxe imediatamente.

O Grimório não está terminado. Mas está fundado. E a fundação é o que importa quando você está construindo sistemas que precisam ser confiáveis no longo prazo.

Se você quer entender como essa plataforma nasceu e evoluiu operacionalmente, o artigo SHIFT, cinco meses depois conta essa história. E se quiser mergulhar em como a CERC pensa liderança e autonomia no contexto de agentes, a série Liderança na Era dos Agentes é o próximo passo.

O repositório está vivo. O Grimório está aberto.

Este post foi escrito por: André Tayer