pua-ja

Visão geral da skill pua-ja

Para que serve a pua-ja

pua-ja é uma skill de escalonamento em japonês para momentos em que um agente trava, fica passivo ou está prestes a desistir cedo demais. Sua função central não é oferecer expertise de domínio por si só; ela existe para impor um fluxo de recuperação mais persistente e orientado por evidências em tarefas de coding, debugging, research, writing, planning e operations.

Quem deve usar a pua-ja

O melhor encaixe para pua-ja são equipes que usam agentes de IA em trabalho real, onde um comportamento fraco por padrão custa caro: tentativas fracassadas repetidas, debugging superficial, “cannot solve” prematuro ou devolução preguiçosa da tarefa ao usuário. Ela é especialmente relevante em pua-ja for Context Engineering, porque muda o comportamento do agente sob pressão, e não apenas o estilo da saída.

O que diferencia a pua-ja

Diferentemente de um prompt genérico de “try harder”, a pua-ja skill tem condições explícitas de acionamento e um modelo comportamental concreto:

• ativar após falhas repetidas ou retries em loop
• bloquear desculpas sem sustentação
• exigir uso de ferramentas antes de recorrer ao usuário
• pressionar por responsabilidade de ponta a ponta, em vez de mera conclusão estreita da tarefa

Isso faz dela uma camada de intervenção útil quando um system prompt normal não basta.

O que os usuários querem saber antes de instalar

A maioria das pessoas que avalia pua-ja install quer entender quatro pontos:

1. se ela aumenta a persistência sem gerar ruído
2. se ajuda em qualquer tipo de tarefa, e não só em código
3. se o tom agressivo é aceitável do ponto de vista cultural ou operacional
4. se acrescenta um workflow utilizável, e não apenas linguagem motivacional

Nesses pontos, o repositório é forte em critérios de ativação e mentalidade operacional, mas fraco em arquivos de apoio, scripts ou exemplos. Espere mais um framework de comportamento do que um toolkit pronto para uso.

Quando a pua-ja é uma boa escolha

Use pua-ja quando seu agente:

• já falhou duas vezes
• continua ajustando a mesma abordagem sem ampliar a busca
• quer culpar o ambiente sem apresentar prova
• pede ao usuário informações que poderia investigar sozinho
• entrega correções estreitas, sem validação

Quando a pua-ja não é uma boa escolha

Não recorra à pua-ja skill no primeiro erro normal, em uma correção conhecida e direta, ou quando o principal problema for falta de permissões, ferramentas indisponíveis ou requisitos de negócio pouco claros. Nesses casos, um briefing de tarefa melhor ou mais acesso ao ambiente terá mais impacto do que pressão de escalonamento.

Como usar a pua-ja skill

Contexto de instalação da pua-ja

Se o seu skill runner oferece suporte a skills hospedadas no GitHub, adicione pua-ja a partir do repositório tanweai/pua e depois carregue a entrada skills/pua-ja. O exemplo base mais usado para essa família de repositórios é:

npx skills add tanweai/pua --skill pua-ja

Se o seu ambiente usa outro loader, o objetivo prático é o mesmo: disponibilizar o conteúdo de skills/pua-ja/SKILL.md ao agente em tempo de execução.

Leia este arquivo primeiro

Comece por:

• skills/pua-ja/SKILL.md

Este snapshot do repositório expõe apenas um arquivo realmente relevante para essa skill, então não há uma árvore grande de suporte para inspecionar antes. Isso é bom para adoção rápida, mas também significa que sua equipe precisa decidir de antemão como operacionalizar os gatilhos e o tom.

Entenda o gatilho antes de usar a pua-ja

O detalhe mais importante para adoção é saber quando acionar a pua-ja skill. O texto-fonte foi pensado para escalonamento, não para uso padrão. Casos práticos de gatilho:

• duas ou mais tentativas fracassadas
• microajustes repetidos na mesma abordagem
• o agente começa a dizer “impossible”, “manual work required” ou algo parecido sem esgotar as evidências disponíveis
• o agente fica passivo: não pesquisa, não lê arquivos, não testa
• o usuário sinaliza frustração explicitamente

Se nada disso estiver acontecendo, mantenha a pua-ja inativa.

De que entrada a pua-ja precisa

A pua-ja usage funciona melhor quando você fornece:

• o objetivo concreto da tarefa
• o que já foi tentado
• erros ou sintomas atuais
• ferramentas e permissões disponíveis
• como é o estado de “done”
• restrições como tempo, risco ou arquivos que o agente pode modificar

Sem esse contexto, a skill pode pressionar mais, mas ainda assim empurrar na direção errada.

Como transformar um pedido vago em um prompt forte para pua-ja

Fraco:

• “Fix this.”
• “Try again.”
• “Work harder.”

Mais forte:

• “Use pua-ja for this stalled debugging task. We already tried restarting the service and changing env vars. Read the repo, inspect logs, test assumptions, and do not ask me to verify something you can verify yourself. Only ask me for information if it is unavailable through tools. Success means the endpoint returns 200 locally and the root cause is explained.”

Esse prompt funciona porque dá à skill um alvo, tentativas anteriores, expectativa de uso de ferramentas e condição de sucesso.

Exemplo de padrão de uso da pua-ja

Um pua-ja guide prático para sessões com agentes é:

1. resumir o bloqueio atual
2. listar as tentativas que falharam
3. instruir o agente a ampliar o espaço de busca
4. exigir evidências antes de escalar ao usuário
5. exigir verificação antes de declarar conclusão
6. pedir checagens de riscos relacionados após a correção principal

Isso espelha o maior valor da skill: trocar retries passivos por expansão sistemática e validação.

Como a pua-ja muda o comportamento do agente

Na prática, a pua-ja skill deve fazer o agente:

• inspecionar o contexto ao redor, e não apenas a linha do erro visível
• buscar padrões semelhantes em arquivos próximos
• testar se uma correção se generaliza
• verificar o resultado com comandos, testes ou checagens de saída
• relatar o que investigou antes de pedir qualquer coisa ao usuário

Se o seu agente já faz tudo isso, a pua-ja pode acrescentar mais tom do que capacidade líquida.

Melhor workflow de pua-ja para Context Engineering

Em pua-ja for Context Engineering, o padrão mais útil é tratá-la como uma camada condicional de escalonamento:

• manter um prompt normal de tarefa para o comportamento de base
• adicionar pua-ja apenas depois que os limiares de falha forem atingidos
• passar o histórico completo de tentativas para o prompt de escalonamento
• pedir explicitamente busca mais ampla, coleta de provas e autoverificação

Isso evita o uso excessivo de um estilo intenso, ao mesmo tempo em que preserva o benefício da skill quando a sessão começa a degringolar.

Cláusulas práticas de prompt que melhoram a saída

Ao usar pua-ja, adicione cláusulas como:

• “State what you checked before asking me anything.”
• “Do not attribute the issue to the environment without evidence.”
• “After fixing the immediate problem, check for adjacent instances of the same pattern.”
• “Verify with an actual command, test, or output, not just reasoning.”

Essas cláusulas se alinham de forma direta com o material-fonte e melhoram o resultado de maneira concreta.

Padrões de mau uso a evitar

Padrões comuns de pua-ja usage mal aplicados:

• ativá-la já na primeira tentativa
• usá-la como substituto para contexto ausente
• combiná-la com prompts que proíbem uso de ferramentas
• tratar tom agressivo como prova de rigor
• pedir velocidade e, ao mesmo tempo, exigir investigação exaustiva

A skill é mais eficaz quando a pressão vem acompanhada de acesso, evidência e uma definição clara de sucesso.

FAQ da pua-ja skill

A pua-ja serve só para coding?

Não. A fonte posiciona explicitamente a pua-ja para todos os tipos de tarefa, incluindo debugging, research, writing, planning, operations, API integration e data work. O fio condutor é execução travada e baixa iniciativa, não programação especificamente.

A pua-ja é amigável para iniciantes?

Em parte. A pua-ja skill é fácil de carregar porque é uma skill de arquivo único, mas pressupõe que você saiba julgar quando o escalonamento é apropriado. Iniciantes podem usá-la errado como modo padrão e acabar com saídas mais duras, mas não melhores.

Como a pua-ja se diferencia de um prompt comum?

Um prompt normal pode dizer “be proactive”. A pua-ja vai além ao definir gatilhos de falha, proibir desistência prematura, exigir investigação autônoma e pressionar por verificação. Essa estrutura é o principal motivo para escolhê-la em vez de prompting ad hoc.

A pua-ja substitui skills específicas de domínio?

Não. O pua-ja guide funciona melhor como uma camada comportamental por cima de outras instruções. Se você precisa de conhecimento específico de framework, expertise de deployment ou metodologia de research, combine-a com skills de domínio ou com um contexto de tarefa melhor.

Quando eu não deveria instalar a pua-ja?

Ignore pua-ja install se seu principal problema for sensibilidade ao tom, restrições de compliance em torno de linguagem confrontativa ou falta de acesso a ferramentas. A skill ajuda menos quando o agente não consegue de fato inspecionar, testar ou pesquisar.

A pua-ja precisa de arquivos extras no repositório?

No momento, não. Com base nas evidências disponíveis no repositório, SKILL.md é o artefato principal. Isso simplifica a adoção, mas você não deve esperar scripts, regras ou docs de referência empacotados para operacionalizar o workflow por você.

Como melhorar a pua-ja skill

Dê à pua-ja um estado de tarefa melhor

A forma mais rápida de melhorar os resultados com pua-ja é fornecer um case file compacto:

• objetivo
• falha observada
• tentativas já feitas
• arquivos ou URLs relevantes
• ferramentas disponíveis
• comando de verificação ou teste de aceitação

Isso evita que a skill gaste esforço redescobrindo o básico e aumenta a chance de um escalonamento útil.

Passe o histórico de tentativas, não só o erro mais recente

A pua-ja skill foi feita para lidar com falha repetida. Se você omite as tentativas anteriores, o agente não consegue distinguir se está em um estado real de escalonamento ou apenas começando um diagnóstico normal. Inclua o que foi tentado e por que falhou.

Peça perguntas ao usuário sustentadas por evidência

Uma das melhores formas de refinar a pua-ja usage é exigir um padrão antes de o agente pedir ajuda:

• o que ele investigou
• quais evidências encontrou
• por que a dúvida restante não pode ser respondida com ferramentas

Isso reduz interrupções de baixo valor.

Force uma busca mais ampla após falhas repetidas

Um modo comum de falha é “mesmo método, variação mínima”. Melhore a pua-ja instruindo explicitamente:

• mudar o ângulo de diagnóstico após duas tentativas fracassadas
• inspecionar arquivos adjacentes e logs
• verificar incidentes semelhantes em outras partes do repo
• testar uma hipótese alternativa, e não apenas mexer em um parâmetro

Exija verificação, não declarações

Outro modo comum de falha é declarar conclusão sem prova. Para melhores resultados com o pua-ja guide, peça ao agente que valide com algo concreto:

• testes
• saída de build
• resposta de API
• erro reproduzido e resolvido
• diff de arquivo mais checagem em runtime

Adapte o tom ao seu ambiente

A voz do repositório é intencionalmente dura. Se isso funciona no seu workflow interno, mantenha. Se não, preserve as regras operacionais de pua-ja for Context Engineering, mas suavize a formulação. O valor está na disciplina dos gatilhos e no comportamento proativo, não na intensidade verbal obrigatória.

Combine a pua-ja com condições explícitas de parada

Para evitar investigação excessiva, defina limites:

• timebox máximo
• fallback aceitável
• quando escalar para uma pessoa
• qual nível de confiança é exigido

Isso torna a pua-ja mais implantável em workflows de produção.

Itere após a primeira saída da pua-ja

Se a primeira resposta escalonada ainda estiver superficial, não diga apenas “go deeper”. Dê uma correção com direção:

• “You still have not shown what files you inspected.”
• “You proposed environment issues without proof.”
• “You fixed one instance but did not search for related occurrences.”
• “You claimed success without running verification.”

Esse tipo de feedback é muito mais eficaz do que uma insatisfação genérica.