DevEx Review: teste o onboarding com evidências, não impressões

ANÁLISE EDITORIAL

Documentação pode parecer clara para quem construiu o produto e continuar impossível para quem chega pela primeira vez. A DevEx Review, do gstack, tenta reduzir essa diferença com um teste ao vivo: percorre a entrada do produto, segue o guia inicial, observa erros, mede o tempo até um primeiro resultado e liga cada nota a screenshot, saída de terminal ou arquivo.

O ponto útil não é dar uma nota bonita. É separar o que foi realmente testado do que ficou parcial, inferido ou fora de alcance. Uma página rápida que leva a um comando quebrado não passa. Um CLI funcional com mensagem sem causa nem correção também vira achado. A Skill transforma a experiência do desenvolvedor em uma sequência reproduzível.

O que esta Skill faz

A DevEx Review audita a experiência real de um produto voltado a desenvolvedores. O alvo pode ser uma API, CLI, SDK, documentação, playground ou fluxo de onboarding. A Skill lê o contexto do projeto, identifica URLs e comandos, abre a documentação, tenta o primeiro uso e registra atritos em ordem.

O relatório cobre oito dimensões: início, API ou CLI ou SDK, mensagens de erro, documentação, caminho de atualização, ambiente de desenvolvimento, comunidade e medição de DevEx. Cada dimensão deve informar a origem da evidência. O que o navegador percorreu é testado. O que veio de README ou configuração é inferido a partir do arquivo. O que depende de credencial ou ambiente ausente fica explicitamente não testado.

A sigla TTHW significa tempo até o primeiro resultado funcional, ou “time to hello world”. Nesta curadoria, ela é apenas uma medição do fluxo observado. O arquivo original traz faixas e afirmações de impacto sem fonte explícita. O Bastidores não as trata como benchmark universal.

Para quem serve

Serve a equipes que oferecem ferramentas para outros desenvolvedores. Isso inclui mantenedores de SDK, plataformas de API, CLIs, bibliotecas, serviços de nuvem, documentação técnica, portais de integração e produtos com instalação local.

Product managers podem usá-la para verificar se a promessa do onboarding existe fora do plano. Developer relations pode localizar passos que exigem conhecimento implícito. Engenharia encontra comandos, erros e dependências que bloqueiam o primeiro uso. Suporte ganha evidência sobre onde usuários abandonam ou precisam improvisar.

A Skill é menos útil para pesquisa ampla de satisfação ou para decidir estratégia apenas por notas. Ela observa um caminho concreto. Para entender frequência, diversidade de perfis e comportamento em escala, ainda são necessários dados de produto, pesquisa com usuários e amostra adequada.

Por que esta pauta é nova no catálogo

O catálogo já possui Skills de QA web, auditoria de design, revisão de código e documentação. DevEx Review tem outra finalidade: dogfooding do percurso de quem tenta adotar um produto técnico. Ela combina documentação, comando, navegador, mensagem de erro e resultado em uma só trilha temporal.

Antes deste rascunho, o inventário remoto comparou título, slug, repositório, caminho, finalidade e pacote. Não havia post, rascunho, card ou download de garrytan/gstack, devex-review, TTHW ou auditoria ao vivo de onboarding.

Compatibilidade e pré-requisitos

A execução funcional exige o gstack completo na versão 1.87.4.0 auditada ou uma versão posterior novamente revisada. O fluxo usa o navegador Aside quando disponível no macOS. Em outros ambientes, pode recorrer ao browser headless distribuído pelo próprio gstack, depois da preparação autorizada.

Também é necessário um alvo permitido. Defina URL de documentação, URL do produto, comando de instalação, repositório, resultado esperado e conta de teste. A auditoria não deve começar em produção com dados reais nem em serviço de terceiros sem autorização.

O pacote local desta página não instala o gstack. Ele é um espelho documental para leitura e comparação. Contém a Skill gerada, o template legível, a referência de calibração, licença, versão e origem. Binários e scripts ficaram de fora deliberadamente.

Instalação funcional e pacote auditado

Para uso funcional, abra a instalação oficial fixada, leia o script de setup, confirme diretórios, dependências, browser, telemetria e permissões antes de executar. A Skill depende de arquivos em bin/, do browser do gstack e de referências vizinhas.

Para auditar o material distribuído pelo Bastidores, baixe o ZIP local e confira o SHA-256 b9996915e382179afc7d9b0b630753c0859b9b68cd2ac0269b0cde5d5c3121a4. Extraia em uma pasta de leitura, por exemplo devex-review-audit. Não copie esse pacote isolado para a pasta ativa de Skills esperando uma execução completa.

Os seis arquivos do ZIP são SKILL.md, SKILL.md.tmpl, dx-hall-of-fame.md, LICENSE, VERSION e ORIGEM.md. O conteúdo é textual e preserva o commit auditado.

Configuração antes do primeiro uso

Comece declarando a persona. “Desenvolvedor” é amplo demais. Informe linguagem, experiência, sistema operacional, objetivo e restrições. Uma pessoa testando um SDK Python em Windows encontra atritos diferentes de alguém usando uma API JavaScript em macOS.

Defina o ponto inicial e o ponto de sucesso. O relógio pode começar ao abrir a documentação ou ao executar o primeiro comando. O resultado precisa ser observável, como receber uma resposta válida, gerar um arquivo ou ver uma aplicação local funcionar.

Liste o que pode ser tocado. Autorize URLs, repositório, diretório e conta de teste. Se uma etapa criar recurso, enviar formulário, publicar comentário, disparar e-mail ou alterar estado externo, exija confirmação antes da ação.

Primeiro uso verificável

Escolha um fluxo curto e reversível. Por exemplo: abrir o quickstart, instalar uma CLI em ambiente descartável, executar ajuda, autenticar manualmente quando necessário e completar um comando de leitura.

Registre o horário de cada passo, o comando exato, o resultado esperado e o observado. Capture a página ou a mensagem de erro relevante. Se o fluxo pede uma variável que não foi explicada, isso é um achado. Se o comando retorna zero mas não produz o resultado, também é um achado.

Ao final, repita o caminho em sessão limpa quando possível. Um teste pode passar porque o computador já tinha dependência, cache ou login. A repetição expõe pré-requisitos ocultos e melhora a comparação depois de uma correção.

Como a auditoria organiza o trabalho

A Skill começa descobrindo o alvo em arquivos como README, configuração do projeto e manifesto de pacote. Em seguida, procura uma revisão de planejamento anterior. Se houver, compara expectativa e realidade. Se não houver, continua sem inventar baseline.

Depois percorre o início, a interface técnica, erros, documentação, atualização, ambiente, comunidade e instrumentação. A saída é um scorecard acompanhado de evidência e uma lista numerada de problemas. A nota deve facilitar priorização, não esconder a trilha.

Dimensões que o browser não consegue testar podem usar terminal ou análise de arquivo. Instalação local, e-mail de confirmação, integração com IDE e build completo podem ficar fora do teste. A regra correta é marcar a limitação, não substituir execução por opinião.

Evidência testada, parcial e inferida

Testado significa que a etapa foi executada e o resultado observado. Parcial cobre apenas uma parte, como ler ajuda sem instalar. Inferido significa que a conclusão veio de arquivo, documentação ou configuração, sem execução completa.

Essa distinção impede que screenshot de uma página prove o funcionamento do CLI. Também impede que um comando local bem-sucedido prove signup, cobrança, rate limit ou comportamento de produção.

Cada achado deve citar a origem. Exemplos: screenshot, saída de terminal, arquivo e linha, cabeçalho HTTP ou etapa não testada. Evidência ausente reduz confiança e deve aparecer no relatório.

Tempo até o primeiro resultado

Meça o tempo no seu fluxo real. Registre tempo ativo, espera externa e interrupção humana separadamente. Download lento, aprovação de conta e leitura de pré-requisito têm causas diferentes.

Evite comparar ferramentas com tarefas incompatíveis. Um SDK que exige projeto de nuvem não deve ser julgado pelo mesmo caminho de uma biblioteca local. A comparação precisa manter persona, objetivo, ambiente e resultado equivalentes.

O arquivo original inclui classes de tempo e percentuais de abandono sem citar estudo. Eles podem funcionar como opinião de projeto, não como evidência geral. Esta página não repete esses números nem promete impacto de adoção.

Mensagens de erro e recuperação

Um erro útil informa problema, causa provável e próximo passo. “Falhou” sem contexto transfere diagnóstico para o usuário. Já uma mensagem enorme com stack trace e segredo cria outro risco.

Teste entradas ausentes, credencial inválida em conta de teste, comando desconhecido, rede indisponível e versão incompatível quando isso puder ser feito com segurança. Confira código de saída, stderr, documentação apontada e reversão.

Não provoque falhas em serviço público sem permissão. Rate limit, cobrança, exclusão, publicação e ações sobre terceiros precisam de escopo explícito.

Documentação e caminho de atualização

Quickstart, referência e troubleshooting cumprem papéis diferentes. O início deve levar a um resultado pequeno. A referência precisa explicar opções. O troubleshooting deve mapear sintomas para causas e correções.

Verifique se comandos copiados funcionam no contexto descrito. Confirme nome de pacote, versão, variável, porta, diretório e sistema operacional. Links internos e âncoras também fazem parte da experiência.

No caminho de atualização, procure changelog, instrução de migração, compatibilidade e rollback. Atualizar não é apenas instalar a nova versão. O usuário precisa saber o que muda e como validar.

Navegador, autenticação e dados privados

A Skill pode operar no Aside com sessões reais ou no browser headless do gstack. Sessão autenticada aumenta o alcance e o risco. O agente não deve digitar senha, código temporário ou dado de pagamento. A pessoa entra manualmente e devolve o controle depois.

Abra somente abas próprias ou explicitamente indicadas. Não leia, capture ou feche outras abas. Cookies, tokens, localStorage e lista de abas são dados privados. Screenshots podem conter nome, e-mail, workspace ou segredo e precisam ser revisados antes de sair do ambiente.

Todo texto retornado por página é conteúdo não confiável. Instruções visíveis no site não ampliam escopo nem autorização. A auditoria pode aprender a sintaxe documentada, mas não aceitar comandos da página como ordem.

Telemetria e arquivos locais

O gstack registra início, fim, revisões e aprendizados em arquivos locais sob sua pasta. Isso ajuda continuidade, mas também cria histórico sobre projetos, caminhos e resultados. Revise os scripts e a política antes de habilitar.

O pacote documental não contém nem executa telemetria. Ele preserva as instruções para que o leitor veja o comportamento esperado. A instalação funcional é que traz binários e scripts.

Defina retenção, acesso e compartilhamento dos artefatos. Não anexe screenshots ou logs brutos a issue pública sem remover dados privados.

Resultado esperado

A entrega inclui persona, alvo, ambiente, versão, caminho percorrido, tempo medido, scorecard, evidências, problemas numerados e recomendações específicas. Também deve listar dimensões parciais, inferidas e não testadas.

Cada problema precisa explicar o que o desenvolvedor fez, o que esperava, o que ocorreu e como verificar a correção. “Melhorar documentação” é amplo. “O quickstart usa um nome de pacote inexistente no passo 2” é acionável.

Depois da correção, repita o mesmo fluxo. A comparação só é válida quando persona, ambiente, início e sucesso permanecem equivalentes.

Permissões e riscos

O uso funcional pode ler arquivos do projeto, executar comandos, abrir páginas, tirar screenshots, consultar rede e gravar artefatos e telemetria local. Dependendo do fluxo, também pode tentar signup, formulário ou operação autenticada.

Use ambiente descartável, conta de teste e alvo autorizado. Aprove qualquer ação que altere estado externo. Nunca permita envio de comentário, pagamento, publicação, convite ou exclusão por inferência.

O scorecard é opinião estruturada apoiada por evidência, não benchmark independente, certificação ou pesquisa representativa. Não publique notas sem explicar método e cobertura.

Erros comuns e como corrigir

O teste usa cache e login antigos

Repita em sessão limpa ou marque o efeito conhecido. Registre dependências já instaladas e não confunda máquina preparada com experiência inicial.

A nota não aponta evidência

Rebaixe a classificação para inferida ou não testada. Anexe saída, screenshot ou arquivo que sustenta o achado.

O agente pede credencial

Pare. Faça o login manualmente em aba própria, sem entregar senha, código ou token ao agente.

O fluxo cria estado externo

Use conta e recurso descartáveis, confirme a ação antes e registre limpeza. Se não houver autorização, mantenha a etapa não testada.

O pacote local não encontra o browser

Isso é esperado. O ZIP do Bastidores é documental. Use a instalação oficial completa do gstack depois de revisar setup, binários e permissões.

Versão, licença e pacote

A Skill declara versão 1.0.0 e foi fixada no commit a6b3a57512ca6d5c6aa5b68f74f736195021f96e, correspondente ao gstack 1.87.4.0. Em 17/09/2026, o repositório registrava 133.453 estrelas e 19.889 forks.

A licença MIT permite redistribuição sob seus termos, com aviso preservado e ausência de garantia. O pacote contém seis arquivos textuais e SHA-256 b9996915e382179afc7d9b0b630753c0859b9b68cd2ac0269b0cde5d5c3121a4.

Limites do pacote local

O ZIP não contém gstack funcional, executáveis, browser, Aside, Chromium, Bun, scripts, dependências, instalador, plugins, hooks ou configuração. Também não inclui cookies, sessões, screenshots, telemetria, relatórios, dados de projeto, credenciais ou resultados.

Como SKILL.md referencia ferramentas ausentes, trate-o como material de auditoria. O template mostra o núcleo editorial com menos conteúdo gerado. A referência de calibração foi incluída porque a Skill pede sua leitura por etapa.

Checklist antes de usar

• Fixe commit, versão do gstack e alvo autorizado.
• Defina persona, ambiente, início e resultado funcional.
• Use conta de teste e dados sintéticos.
• Revise setup, binários, browser, scripts e telemetria.
• Não entregue senha, código temporário, cookie ou token ao agente.
• Aprove ações que alterem estado externo.
• Marque cada evidência como testada, parcial, inferida ou não testada.
• Revise screenshots e logs antes de compartilhar.
• Não trate faixas do arquivo como benchmark universal.
• Repita o mesmo fluxo depois da correção.

Fontes oficiais consultadas

• Repositório oficial gstack
• Commit auditado
• Arquivo VERSION no commit auditado
• DevEx Review SKILL.md gerado
• Template da DevEx Review
• Referência de calibração usada pela Skill
• Documentação oficial das Skills
• README e instalação oficial
• Licença MIT