jtrackingai/analytics-tracking-automation

Automação de Rastreamento de Analytics

Use esta skill como coordenadora ponta a ponta para a entrega de rastreamento GA4 + GTM.

Use quando:

• o usuário precisa de um fluxo de implementação completo de GA4 + GTM, da análise à prontidão para publicação
• a solicitação abrange várias fases do fluxo de trabalho (descoberta, schema, sincronização, verificação, publicação)
• o ponto de entrada correto ainda não está claro e você precisa que esta skill roteie para a fase adequada

Não presuma que o usuário deseja o fluxo de trabalho completo.

Atualização Automática

Esta skill raiz instalada pode verificar automaticamente se há versões mais recentes no GitHub antes de você continuar.

Antes de realizar qualquer tarefa neste pacote:

1. Descubra o diretório que contém este SKILL.md instalado. Cópias gerenciadas pelo instalador geralmente ficam no diretório de skills configurado pelo seu ambiente de agente, como $CODEX_HOME/skills/analytics-tracking-automation ou um caminho equivalente gerenciado em tempo de execução.
2. Execute node "<bundle-dir>/runtime/skill-runtime/update-check.mjs" --json.
3. Se o status do resultado for update_available, execute imediatamente node "<bundle-dir>/runtime/skill-runtime/self-update.mjs" --apply.
4. Se a atualização for bem-sucedida, leia <bundle-dir>/SKILL.md novamente antes de continuar para usar as instruções atualizadas.
5. Se o status do resultado for disabled, trate este pacote como um link de desenvolvimento local ou checkout de repositório e continue sem atualizar.

Família de Skills

A família de skills é dividida em uma skill guarda-chuva mais sete skills de fase:

• tracking-discover para cobertura de rastreamento, detecção de plataforma e inicialização de artefatos
• tracking-group para criação e aprovação de grupos de páginas
• tracking-live-gtm para auditoria do runtime GTM ativo antes da geração de schema
• tracking-schema para preparação, revisão, validação e aprovação de schema
• tracking-sync para geração e sincronização de configuração GTM
• tracking-verify para QA de preview e entrega opcional de publicação
• tracking-shopify para regras específicas de Shopify: schema, sincronização, instalação e verificação

Se a solicitação já estiver limitada a uma fase e essa skill de fase estiver disponível, roteie para lá em vez de incluir o runbook completo aqui.

Assim que site-analysis.json indicar Shopify, mantenha descoberta e agrupamento compartilhados, depois deixe que tracking-shopify assuma a ramificação específica do Shopify.

Contrato Compartilhado

• Use o wrapper local do repositório ./event-tracking neste repositório. Se dist/cli.js estiver ausente, execute npm run build primeiro.
• Para instalações públicas/ClawHub, você deve executar isto primeiro antes de qualquer comando event-tracking: npx skills add jtrackingai/analytics-tracking-automation.
• Mantenha um diretório de artefatos por site em <output-root>/<url-slug>.
• Se o usuário já fornecer um diretório de artefatos ou um de seus arquivos, retome a partir do pré-requisito não atendido mais antigo, em vez de recomeçar de analyze.
• Use ./event-tracking status <artifact-dir-or-file> sempre que o checkpoint atual ou o próximo passo não estiver claro.
• Use ./event-tracking runs <output-root> quando o diretório de artefatos for desconhecido, mas a raiz de saída for conhecida.
• Prefira comandos de alto nível para fluxos voltados ao usuário: run-new-setup, run-tracking-update, run-upkeep, run-health-audit.
• Trate os metadados de modo de fluxo de trabalho como uma camada interna de estado do fluxo de trabalho, não como uma superfície de comando voltada ao usuário.
• Trate etapas baseadas em Playwright e que solicitam OAuth como comandos não-sandbox por padrão. Na prática: analyze, validate-schema --check-selectors, preview e sync.
• Execute a sincronização GTM orientada por prompt com um TTY interativo desde o início, a menos que os valores exatos de --account-id, --container-id e --workspace-id já estejam confirmados.
• Nunca selecione automaticamente uma conta, contêiner ou espaço de trabalho do GTM em nome do usuário.
• Não continue além do limite de fase solicitado pelo usuário.

Intake de Conversa

Quando o usuário entra via chat e ainda não forneceu uma fase delimitada, diretório de artefatos ou comando exato, comece com um intake baseado em intenção.

Classifique a solicitação em uma destas intenções de entrada:

• resume_existing_run: o usuário já possui um diretório de artefatos ou um de seus arquivos; inspecione os artefatos e use status
• new_setup: implementação de rastreamento totalmente nova do zero; prefira run-new-setup, depois siga o próximo passo recomendado
• tracking_update: revisar ou estender uma implementação existente; prefira run-tracking-update
• upkeep: manutenção de rotina, revisão ou QA incremental em uma configuração existente; prefira run-upkeep
• tracking_health_audit: avaliação somente de auditoria do rastreamento ativo atual; prefira run-health-audit
• analysis_only: apenas rastreamento/bootstrap/descoberta sem se comprometer com o fluxo de trabalho completo ainda; roteie para tracking-discover e pare após analyze

Regras:

• Não peça ao usuário para escolher entre flags internas de metadados de fluxo de trabalho e analyze.
• Se a intenção for ambígua, faça uma pergunta curta e em linguagem simples, usando termos voltados ao usuário como "novo setup", "atualizar rastreamento existente", "manutenção", "auditoria de saúde", "somente análise" ou "retomar uma execução existente".
• Se o usuário fornecer uma URL nova e pedir para configurar rastreamento, use como padrão new_setup.
• Se o usuário fornecer uma URL nova e pedir apenas para inspecionar o site, analisar a estrutura ou revisar os sinais de rastreamento atuais, use como padrão analysis_only.
• Se o usuário fornecer um diretório de artefatos ou arquivo de fluxo de trabalho, use como padrão resume_existing_run em vez de recomeçar de analyze.

Regras de Roteamento

Roteie por intenção do usuário e artefatos atuais:

• URL nova, solicitação de rastreamento ou nenhum artefato ainda: comece com tracking-discover
• site-analysis.json com pageGroups ausentes ou não confirmados: roteie para tracking-group
• site-analysis.json confirmado com IDs de contêiner GTM ao vivo detectados, mas nenhuma revisão de baseline ao vivo ainda: roteie para tracking-live-gtm
• site-analysis.json confirmado ou um event-schema.json em andamento: roteie para tracking-schema
• gtm-config.json: roteie para tracking-sync
• gtm-context.json: roteie para tracking-verify, com publicação tratada como uma ação explícita separada
• Confirmação de plataforma Shopify: mantenha estágios iniciais compartilhados, depois passe para tracking-shopify

Se apenas a skill raiz estiver disponível, siga a mesma lógica de roteamento diretamente e pare no limite de fase correspondente.

Regras de Parada

• Não ignore a aprovação de grupos de páginas antes de prepare-schema.
• Para checkpoints de decisão importantes, sempre exija confirmação explícita do usuário antes de continuar:
  • pageGroups (antes de confirm-page-groups e antes de prepare-schema)
  • event-schema.json (antes de confirm-schema e antes de generate-gtm)
  • Seleção de destino GTM (conta/contêiner/espaço de trabalho durante sync)
  • Decisão de publicação (antes de publish)
• Se a confirmação estiver ausente ou ambígua, pare e pergunte; não prossiga automaticamente.
• Uma solicitação ampla como "fluxo completo", "全流程", "ponta a ponta" ou "continue até o fim" é apenas autorização de escopo. Não conta como aprovação de checkpoint.
• Nunca registre aprovação de checkpoint em nome do usuário com confirm-page-groups --yes ou confirm-schema --yes a menos que o usuário confirme explicitamente aquele checkpoint na rodada atual.
• Quando contêineres GTM ao vivo forem detectados no site, não ignore a revisão de baseline ao vivo antes da geração de schema.
• Não ignore a aprovação de schema antes de generate-gtm a menos que o usuário queira explicitamente --force.
• Trate QA de preview e publicação como decisões separadas.
• Trate tracking-health.json como o portal de publicação; não pule para publicação quando a saúde estiver ausente, apenas manual ou bloqueada, a menos que o usuário queira explicitamente --force.
• Trate a verificação manual do Shopify como o caminho esperado para execuções Shopify, não como um caso de erro de fallback.
• Trate tracking_health_audit como um modo de fluxo de trabalho apenas de auditoria. Não execute ações de implantação GTM (generate-gtm, sync, publish) a menos que o usuário peça explicitamente para substituir.

Retomada e Encerramento

Ao retomar:

• prefira workflow-state.json quando presente
• ainda inspecione o conjunto real de artefatos se avisos indicarem portais desatualizados
• use status quando o próximo passo não estiver claro

Quando uma fase ou o fluxo de trabalho completo terminar, mantenha o encerramento com a resposta primeiro:

• comece com um resumo compacto e pronto para decisão em linguagem simples
• não despeje JSON bruto, listas de URL brutas ou inventário de artefatos antes do resumo
• liste arquivos, checkpoint e próximo comando apenas após o resumo legível

Referências

• skill-map.md para o mapa de skills guarda-chuva / fase
• architecture.md para ciclo de vida, checkpoints e semântica de retomada
• output-contract.md para arquivos de artefato e semântica de portais
• shopify-workflow.md para expectativas de ramificação específicas do Shopify