Process Documenter

Process Documenter

Descrição

Lê a configuração de um pipe do Pipefy e escreve a documentação do processo: por onde o trabalho entra, quais fases existem e em que ordem, o que cada fase exige para o card sair dela, onde há prazo, o que já é feito por automação, quem participa e quais caminhos de exceção estão previstos.

Duas entregas, escolhidas pelo pedido do usuário e não por padrão:

• Procedimento operacional. Para quem executa: o que fazer em cada fase, na ordem, com o que é obrigatório e o que acontece sozinho.
• Mapa de configuração. Para quem revisa ou audita: o que está configurado, o que está desligado, o que está previsto e não é usado, e onde a configuração não sustenta o que a documentação precisaria afirmar.

Três fontes, com autoridade diferente, e a skill nunca as mistura:

• A configuração diz o que o sistema exige. É a única fonte que vale como regra.
• Os cards dizem o que o time faz. Servem para confirmar ou contradizer a configuração, nunca para inventar regra que ela não tem.
• O motivo não está em lugar nenhum. Por que a alçada é de dez dias, por que aquele campo é obrigatório, qual norma exige aquele anexo: nada disso está na API. Vai marcado como pendente de confirmação com o dono do processo, jamais preenchido por dedução.

Esta skill lê. Não altera nada no Pipefy: nem fase, nem campo, nem automação, nem descrição.

Usa apenas as ferramentas do MCP do Pipefy. Não há script nem dependência a instalar: só este arquivo e os arquivos de referência ao lado dele.

Quando usar

• Alguém novo assume o processo e não existe documentação.
• Auditoria, certificação ou cliente pede o procedimento escrito.
• Antes de redesenhar um processo, para registrar como ele está hoje.
• Para treinar quem vai operar o pipe.
• Para descobrir o que a configuração exige de fato, quando a documentação existente e a prática divergem.

Para diagnóstico, com gargalo, retrabalho e prazo violado, use a skill process-health: esta aqui descreve o processo, não o julga. Para um card específico, use card-summarizer.

Referências

Este arquivo é o fluxo. O detalhe mora em references/, e cada arquivo é lido no passo que precisa dele, não antes.

Fluxo

1. Coletar a configuração. Leia references/collect.md e siga: estrutura do pipe, formulário de entrada, campos por fase, automações, condições de campo, etiquetas, membros, agentes de IA e conexões com outros processos.

2. Amostrar a prática. Ainda em references/collect.md. Uma amostra pequena de cards, agregada por página, serve para uma pergunta só: o que a configuração prevê está sendo usado? Ela não mede desempenho. Se você começar a calcular mediana de fase, parou de documentar e virou a process-health com amostra insuficiente.

3. Documentar. Leia references/document.md. Monte o documento fase por fase, derive o critério de saída das três fontes que o produzem, registre as divergências entre o previsto e o observado, e marque como lacuna tudo que a configuração não afirma. Lacuna declarada é entrega; lacuna preenchida por dedução é documentação errada, que é pior que nenhuma.

4. Responder. Leia references/response.md e escolha a entrega pelo que o usuário pediu. A entrega é tabular: uma linha por fase e uma tabela de lacunas, com legenda de uma linha. Documento em prosa parece completo e não é consultável, porque quem abre tem uma pergunta sobre uma fase e precisa achar a linha dela sem ler as outras. O que não couber na linha é lacuna, não texto.

5. Perguntar o que vem depois, de forma interativa. Feche com a ferramenta de pergunta interativa do ambiente (AskUserQuestion no Claude Code), não com uma frase solta. Uma pergunta, escolha única, com as opções da seção "Fechamento" de references/response.md.

6. Publicar, só se pedirem. Nunca publique por iniciativa própria. Quando o usuário escolher publicar, leia references/publish.md, use a ferramenta Artifact e entregue o link. Não gere arquivo HTML local. O artefato nasce privado, e quem decide abrir é o usuário.

Governança

• Nada de vocabulário de API na tela, em nenhum momento. A proibição não vale só para o documento final: vale para o que você escreve enquanto coleta. Não narre nome de ferramenta, de consulta ou de campo da API, nem em relato de progresso, nem em aviso de erro, nem para justificar uma lacuna. Em vez de "chamando get_automations", escreva "lendo as automações do processo"; em vez de "get_field_conditions falhou", escreva "não consegui ler as regras de campo, e por isso elas ficam como lacuna". Os identificadores existem dentro da chamada de ferramenta, e é lá que eles ficam. A lista do que nunca aparece está em references/response.md.
• Documento sem data de leitura envelhece sem ninguém notar. Toda entrega declara a data da coleta e que descreve a configuração daquele momento. Pipe muda, e documentação que parece atemporal é a que engana.
• Os valores dos campos passam pelo seu contexto na amostra de prática, porque a API não permite pedir apenas o preenchimento. O documento descreve o campo, não o conteúdo dele: nunca transcreva valor de campo de card. Cite exemplo apenas quando ele vier da configuração, como as opções de uma escolha única.
• Em pipe com dado sensível (folha de pagamento, saúde, jurídico de pessoa física), avise o usuário antes de coletar a amostra de prática. A configuração sozinha não traz dado de pessoa.
• Nomes de pessoas. Membros e responsáveis aparecem no documento como papel, não como lista de nomes, a menos que o usuário peça o contrário. Procedimento nominal fica errado na primeira mudança de time.
• Ao compartilhar, confira se o público pode ver aquele processo. Documentação circula mais que relatório, e ela expõe a estrutura inteira.
• Nada é preenchido por semelhança. Você conhece processos parecidos e isso é uma armadilha aqui: nunca escreva a etapa que "normalmente existe" em um processo de compras se ela não está no pipe. O documento descreve este pipe.
• Nenhuma alteração no Pipefy sai desta skill. Se o usuário quiser corrigir uma lacuna, como preencher a descrição de uma fase, isso exige confirmação explícita dele sobre o que exatamente será alterado.
• Processos que continuam em pipe conectado não são atravessados. Se childrenRelations ou parentsRelations existirem, o documento diz onde o trabalho sai deste pipe e que a descrição para na fronteira.

Critério de qualidade

O documento está pronto quando declara a data da coleta e o que foi lido; cobre todas as fases na ordem real, incluindo as que a amostra não usou; separa o que o sistema exige do que o time faz, com a fonte de cada afirmação; marca como lacuna todo critério de saída, prazo ou responsável que a configuração não define, em vez de completar; nomeia papéis e não pessoas; registra as divergências entre previsto e observado sem escolher um lado em silêncio; cabe em uma linha por fase mais a tabela de lacunas; não contém nenhum identificador interno de API nem nome de ferramenta, nem no documento nem no que você escreveu antes dele; e termina em uma única próxima ação, que costuma ser confirmar as lacunas com o dono do processo.

Antes de entregar, releia procurando underscore e inglês técnico. Achou algum fora de bloco de código, traduza.

Uma fase cuja única descrição possível é o próprio nome é uma lacuna, não uma seção curta. Escrever "Nesta fase o card é analisado" sobre uma fase chamada Análise não documenta nada, e dá a impressão de que documenta.