Extrai comentarios de revisao de Docs/.docx de um cliente e grava como conhecimento markdown (feedbacks/ + brain/_pending) num projeto Conversion Agent, com dedup incremental.
-
Resolver o projeto-alvo. Chame get_active_project. Se houver projeto ativo,
use seu ws_slug/proj_slug. Se null, pergunte à usuária qual projeto (formato
workspace/projeto, ex.: conversion/nike-bi) e confirme antes de seguir.
Nunca infira ws/proj.
-
Pedir o client_id. Peça o id do cliente (inteiro, ex.: 1071). É esse id
que descobre os documentos comentados do cliente — não há mais pasta do Drive a
informar.
-
Descobrir os documentos (MCP mcp__conversion__feedback_sources). Esta é uma
chamada à tool MCP mcp__conversion__feedback_sources — não é um script
local. Invoque-a passando exatamente { client_id: <inteiro> } (o id do passo 2). A
tool consulta o backend e devolve { rows: [...] }, onde cada row tem
{ txt_link, Created_Date, fk_cliente }. Colete os txt_link (as URLs dos
documentos comentados), preservando a ordem — é essa lista que alimenta o extractor
no passo 5.
- Se a tool retornar
not_authenticated / session_expired, faça o login
transparente (magic link) e repita a chamada antes de seguir. Não peça pra
usuária autenticar manualmente — você conduz.
- Se
rows vier vazio, informe à usuária que o cliente <client_id> não tem
documentos de feedback registrados e pare (nada a extrair).
-
Garantir auth do Drive (Google ADC). Rode:
python "${CLAUDE_PLUGIN_ROOT}/skills/sync-feedbacks/scripts/drive_auth.py" --whoami
Se imprimir o e-mail @conversion.com.br, siga. Se falhar (ADC ausente ou sem o
escopo do Drive), o próprio script imprime o comando de login. Como o login Google
abre o browser e exige interação, esta é a exceção à regra de conduzir sozinho:
peça à analista que rode o login no chat com o prefixo !:
! gcloud auth application-default login --scopes=https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/cloud-platform
Cada analista loga com a própria conta Google — sem nenhum arquivo do squad BI.
Depois rode o --whoami de novo para confirmar.
-
Extrair os comentários. Defina um workdir, escreva as URLs (txt_link do passo 3,
uma por linha) num arquivo, e rode o extractor (passe os slugs reais resolvidos no
passo 1):
WORKDIR="$HOME/.conversion-feedbacks/_run-<proj>"
rm -rf "$WORKDIR" && mkdir -p "$WORKDIR"
python "${CLAUDE_PLUGIN_ROOT}/skills/sync-feedbacks/scripts/extract_comments.py" extract \
--docs "$WORKDIR/_docs.txt" --ws <ws> --proj <proj> --workdir "$WORKDIR"
A lista de URLs pode vir por arquivo (--docs <arquivo>) ou por stdin (--docs -).
Flags opcionais: --only-open (ignora comentários resolvidos; o default inclui e
sinaliza [RESOLVIDO]), --rebuild (reprocessa tudo, ignorando o dedup).
O script imprime um resumo JSON (counts new/changed/skipped/no-comments/error +
lista to_save) e grava feedbacks/*.md em $WORKDIR/feedbacks/.
-
Persistir os feedbacks no projeto (MCP). Se to_save estiver vazio, pule para
o passo 9 (nada novo). Senão, leia cada arquivo em $WORKDIR/feedbacks/*.md (Read)
e grave todos num único project_save_batch, passando ws_slug/proj_slug e
files[] com path = feedbacks/<arquivo>.md + content. Inclua no mesmo batch
o arquivo do brain do passo 7. Guarde a URL retornada.
-
Ponte com o brain — um arquivo por rodada (fecha o loop). A partir dos
comentários novos/alterados, destile os padrões recorrentes e acionáveis (ex.:
"cliente sempre pede CTA mais direto", "evitar jargão X", "datar dados") como uma lista
enxuta de propostas — não copie comentário a comentário, sintetize. Grave num
arquivo novo e exclusivo desta rodada, usando o round_id do resumo do passo 5:
path = brain/_pending-feedbacks-<round_id>.md (ex.: brain/_pending-feedbacks-2026-05-28-1432.md).- Inclua esse arquivo no mesmo
project_save_batch do passo 6.
- Não mantenha cópia cumulativa local e não reescreva arquivos de rodadas
anteriores. Cada rodada é um arquivo independente.
Por que um arquivo por rodada: a humana revisa e, ao promover, apaga aquele arquivo
— e ele nunca reaparece, porque rodadas futuras só criam arquivos com round_id
novo (e o dedup do passo 5 garante que um doc já processado não volta a gerar proposta,
salvo --rebuild, que cria outro arquivo datado, sem tocar nos antigos).
Esse arquivo é propriedade desta skill — não toque em brain/_pending.md, que é
do ritual brain-vivo (/brain-update). A humana revisa brain/_pending-feedbacks-*.md
e promove o que valer para brain/aprendizados.md / brain/glossario.md /
brain/decisoes.md — é a promoção que faz /briefing e /redator pararem de repetir
os erros (porque read_brain lê só os 5 arquivos definitivos).
-
Confirmar o manifest (dedup). Só depois do project_save_batch ter
sucesso, rode:
python "${CLAUDE_PLUGIN_ROOT}/skills/sync-feedbacks/scripts/extract_comments.py" commit \
--ws <ws> --proj <proj> --workdir "$WORKDIR"
Isso marca os docs gravados como processados (por fingerprint), para a próxima
rodada pular o que não mudou. Se o save falhar, não rode o commit — assim o
doc é reprocessado na próxima vez.
-
Reportar. Devolva à usuária, em linguagem de cliente:
- A URL web do save (passo 6).
- Resumo: N feedbacks gravados (novos/alterados), N pulados (sem mudança), total de
comentários, quantos resolvidos.
- Se houve propostas de brain: aponte o arquivo da rodada
brain/_pending-feedbacks-<round_id>.md para revisão e lembre que promover para
aprendizados.md (e apagar o arquivo da rodada) é o que alimenta as skills de conteúdo.
- Erros por documento (status
error no resumo), se houver.
