Briefing executivo
Tudo que você precisa para conduzir a conversa: o que a Vyva é, onde ela se diferencia das ferramentas de mercado, até onde ela vai, e o que o caso do TABG prova. Cada afirmação aqui tem lastro nos documentos do projeto.
A primeira pergunta que vão fazer é “o que é isso, exatamente”. A resposta curta evita que a conversa vire “mais uma IA”.
27 comandos que rodam dentro do Cursor, apoiados em 18 pacotes JavaScript que fazem a parte mecânica. Instala por script, versiona junto do projeto, trabalha numa pasta própria dentro dele.
Nada vai para serviço externo: o PDF confidencial é lido na máquina de quem conduz.
O cliente leva regras com identificador, critério e origem; a lista do que a fonte não fecha; um protótipo para corrigir o entendimento; e a spec que o time executa.
Frase pronta: “Vocês não levam a ferramenta. Levam as regras prontas para construir, feitas com um profissional nosso.”
PDF, documento, planilha, protótipo anterior, issues e wiki existentes — e a conversa com o PO.
Catálogo de requisitos, protótipo navegável, spec de construção, texto de validação, wiki, issues e um relatório vivo.
Imagem e PDF escaneado não fundamentam requisito. O código de produção não é escopo desta ferramenta.
Onde ela se posiciona no mercado
Pedir o sistema direto ao agente produz código que parece certo e erra a intenção. GitHub e Microsoft responderam com spec-driven development: a especificação vem antes e vira a fonte da verdade do humano e da IA.
Spec Kit (GitHub), Kiro (Amazon), Tessl. Birgitta Böckeler, no site do Martin Fowler, separa três níveis: a spec guia a tarefa, a spec continua viva para a feature, ou a spec é o único arquivo que o humano edita.
Essas ferramentas começam na intenção escrita pelo engenheiro, num repositório que já existe. A Vyva começa um passo antes: na fonte do cliente.
A parte de engenharia — o que distingue a Vyva de um prompt bem escrito.
Quem faz o quê
| Camada | Faz | Nunca faz |
|---|---|---|
| IA | Lê a fonte como uma pessoa leria. Separa sinal de ruído. Agrupa por significado, funde duplicata, escreve o enunciado na voz da organização, sintetiza o critério, decide o recorte das telas. | Não cunha identificador. Não escolhe lado em conflito. Não inventa estrutura que o material não declara. |
| Harness | Cunha os identificadores. Liga a proveniência. Monta índice, PRD e registro de decisões. Calcula cobertura e o selo de pronto. Mesma entrada, mesma saída. | Não decide significado de negócio. Não resolve ambiguidade. |
| Portões | Sete checagens por fatia do protótipo. Critério só fica verde com veredicto de teste. Versão só publica com todas as perguntas fechadas. | Não deixa passar fatia sem rastreio. Não pinta de verde por navegação manual. |
| PO | Decide o recorte, responde a entrevista, aprova a consolidação, resolve conflito, autoriza o que vai para wiki, issue, demo e remoto. | Não opera git. Não decora comando: a porta /vyva escolhe a disciplina. |
Por que isso importa para quem lidera tecnologia: o que varia entre execuções é a redação. O que o time depende — identificador, rastreio, cobertura — é determinístico. É o oposto de um chat em que cada rodada produz um artefato diferente.
O caminho de um caso novo
Cada trecho relevante vira evidência com origem e peso. Fonte prioritária pesa mais.
Agrupa por significado, nunca um trecho por requisito. Cada item sai com critério. Lacuna vira dúvida aberta.
Fatia por funcionalidade. Cada ação aponta o requisito. Sem tela: não atendido. Sem requisito: órfã.
Do código saem casos de uso, modelo de dados, matriz de rastreio e o relatório de honestidade.
Requisito, protótipo e fonte nova se cruzam. Só a feature tocada regenera.
Sem material prévio, o passo 2 começa por uma entrevista guiada. Com a fonte na mesa, a entrevista encolhe para as lacunas.
Triangulação — por que a spec não envelhece
É justamente o buraco que a literatura aponta nas ferramentas de mercado: ninguém diz como a spec se mantém depois da primeira rodada.
Não é uma fila. São três cantos, e o protótipo é saída e fonte: se o PO mexe na tela, esse diff volta como evidência. Por baixo, um merge de três vias — mesma mecânica do git, com requisito no lugar da linha.
Os dois lados divergiram: vira pergunta numerada, com os três textos à vista. A versão só publica quando todas fecham.
Feature estável não é reprocessada — isso é correção, não economia. Re-sintetizar o corpus inteiro a cada rodada explode em ruído.
A parte que um time técnico vai querer sondar: em que é feita, o que usa, qual a lógica de execução e o que protege o cliente.
Stack
| Camada | Tecnologia | Por quê |
|---|---|---|
| Runtime | Node 18+, JavaScript puro em módulos ES. Monorepo com workspaces npm: 18 pacotes @you-reqs/*, versão 0.1.5. | Sem build, sem framework, sem serviço. Roda na máquina de quem conduz e em CI do mesmo jeito. |
| Interface | Skills do Cursor — cada comando é um documento de disciplina que orquestra chamadas aos pacotes. | O modelo faz julgamento; o pacote faz a operação. Trocar de modelo não muda o artefato. |
| Leitura de fontes | pdfjs-dist para PDF, mammoth e word-extractor para Word, tesseract.js (OCR em WASM) como último recurso. | Tudo JavaScript ou WebAssembly: nunca exige binário nativo instalado, nunca depende do sistema operacional do usuário. |
| Análise do protótipo | espree — o portão de legibilidade percorre a árvore sintática do código. Nunca expressão regular sobre o texto-fonte. | A verificação enxerga estrutura real, não aparência. Não há como burlar com formatação. |
| Contratos | JSON Schema validado com ajv, para veredictos de teste e manifesto do workspace. | O que atravessa cada etapa é validado, não presumido. |
| Dados do protótipo | SQLite em WebAssembly quando o projeto é relacional; chave-valor só quando não é — sempre atrás de uma interface de repositório. | O protótipo já se parece com o sistema real, e a virada para banco de verdade fica mecânica. |
| Qualidade da ferramenta | Pipeline GitLab CI em Node 18, com estágios de lint, teste e publicação. | A própria Vyva é versionada e testada antes de virar release. |
A lógica: transformadores sobre contratos de arquivo
O princípio que organiza tudo: cada etapa é um transformador com um contrato estável dos dois lados. O contrato é o produto; a skill é substituível.
| Junta | Artefato | O que ele garante |
|---|---|---|
| 1 | Evidências em JSONL | Cada unidade tem identificador, origem (arquivo, página, seção), modalidade e peso. Fonte prioritária pesa mais e orienta conflito. |
| 2 | PRD + índice + registro de decisões | Requisitos e critérios com identificador cunhado pela máquina, cada um ligado às evidências que o justificam. O registro guarda cada instrução do PO, por fase, e sinaliza contradição. |
| 3 | Fatias do protótipo | Cada funcionalidade em cinco arquivos com papéis fixos: estado, ações, repositório, tela e intenção. Toda ação declara o requisito que atende. |
| 4 | Pacote de especificação | Interface, modelo de dados, casos de uso, matriz de rastreio e relatório de honestidade — levantados do código, não redigidos à mão. |
A cadeia de rastreio, ponta a ponta
evidência E-0001 → justifica → requisito RF02 + critério CA06
→ implementado por → ação registrarChegada @req RF02
→ verificado por → teste do CA06 ⇒ veredicto
→ elevado para → endpoint na especificação
De qualquer linha da spec dá para voltar até a cláusula do documento que a exigiu, e avançar até o teste que a prova. É o que torna “protótipo é especificação” auditável, e não retórica.
Determinismo — onde ele está e onde não está
As funções puras recebem o relógio e a versão por parâmetro — não leem a hora sozinhas. Rodar duas vezes dá o mesmo arquivo, byte a byte.
Admitir isso é o ponto. A variabilidade fica confinada ao texto, que o PO revisa. A estrutura de que o time depende não varia.
Segurança e contenção
Uma pergunta por mensagem, com alternativas quando são previsíveis. Nenhuma gravação acontece no silêncio.
| Momento | O que ela pergunta | O que ela não faz |
|---|---|---|
| Entrevista do zero sem material prévio | O quê, quem, quando, onde, por quê e como — só em regra de negócio. Reescreve o entendimento e espera confirmação. | Não escreve o PRD antes de fechar as fases. Não pergunta banco nem framework: isso é a spec, não o levantamento. |
| Checklist de fontes sempre, mesmo parecendo completo | Tem mais insumo? Tem link remoto? Qual fonte ganha num conflito? Depois, a lacuna que o documento deixou. | Não vira um trecho em um requisito. Não resolve contradição entre fontes sozinha. |
| Consolidação | Aprovado, ajustar um ponto, ou refazer o bloco. | Não cunha identificador antes do sim. |
| Groom no protótipo | “Isso refina esta história. Confirma?” Fala sobre campo ou tela pede um segundo sim. Depois de mudar uma fatia, oferece gerar o teste do critério. | Não grava história, tela ou teste em silêncio. Não abre issue a partir do groom. |
| Conflito | Mostra base, a edição do PO e a fonte nova. Ele escolhe um lado ou escreve um híbrido. | Não descarta a edição manual. Não publica versão com pergunta aberta. |
| Publicação | Sincronizar confirma antes. Wiki mostra o diff. Issue pede qual item abrir, um por vez. Demo pede a senha. Aceite pergunta se abre issue e se a demo sai do ar. | Não faz push forçado. Não grava wiki, issue nem aceite sozinha. |
Groom, na prática
PO“O carregador só acompanha a própria estadia.”
VyvaLê as histórias daquela feature. “Isso refina a história do acompanhamento. Confirma?”
POConfirma, aponta outra história, pede uma nova, ou cancela.
A história fica gravada por feature, o relatório atualiza, e o GitLab não recebe nada.
O PO dá a ordem em linguagem natural e a ferramenta filtra o que já está pronto: enunciado, proveniência, ao menos um critério, requisitos ligados prontos, fluxo definido e nenhuma pergunta aberta.
Não cria história nessa hora, e também não publica no tracker. Quem reprova volta com a lista do que falta.
Os cinco passos são o caminho. O resto sustenta o trabalho depois que o caso existe.
Levantar
Conduz o levantamento do zero, por fases, uma pergunta por vez, até um PRD rastreável.
Lê cada fonte e materializa evidências com origem e peso. Documento confidencial não sai da máquina.
Sintetiza os requisitos reais com critério, porquê, para quê, quem pediu, dependência e glossário — tudo ancorado em evidência.
Materializar
Gera o MVP simulado, fatiado por funcionalidade, com rastreio em cada ação e marcador visível onde a garantia é fingida.
Eleva o protótipo a interface, modelo de dados, casos de uso, matriz de rastreio e relatório de honestidade.
A mesma verdade em linguagem de validação: o que entra, o que fica de fora, como se usa, como saber que está certo.
Refinar e acompanhar
Transforma a conversa sobre o protótipo em história daquela feature, sempre com confirmação.
Aplica o gate de prontidão sobre as histórias existentes e grava o recorte da sprint, local.
Sobe a página viva do relatório: contagens, fontes, requisitos, tela ligada à feature, pendências, com o protótipo ao lado.
Mantém o continuum entre requisito, protótipo e spec, feature a feature, com os conflitos virando perguntas.
Versionar — o histórico que não se perde
Checkpoint local e reversível. Sem descrição, a mensagem diz honestamente o que mudou.
Abre versão paralela, lista o histórico e junta de volta com prévia do delta. Conflito em linguagem de feature, não em diff cru.
Manda a versão ao repositório de metadados e tenta merge normal. Confirma antes. Push forçado é proibido.
Integrar com o time
Cruza as features com as issues existentes — e com diagrama e wiki, se houver — e descreve o work item. Lê o GitLab; não escreve.
Publica uma issue por vez, sob ordem explícita, a partir do item conciliado, nas seções que a casa já usa. Não cria branch nem épico.
Propõe regra, índice, glossário e decisão a partir da spec. O PO vê o diff. Sem sim, não grava.
Fechar com o cliente · manter a ferramenta
Publica o protótipo navegável, com senha por padrão e aviso em toda tela de que é protótipo.
Registra a aprovação de forma auditável. Depois pergunta se abre issues e se a demo pode sair do ar.
Um GitLab e um token no caso comum; dois papéis quando a infra da YouX e o GitLab do cliente são contas diferentes. Token nunca aparece no chat.
Encapsula projeto antigo preservando histórico; e puxa a versão estável da ferramenta.
Requisito sempre com os mesmos campos. Critério sempre em Dado, Quando, Então. Issue sempre nas seções da casa. Protótipo sempre com a mesma anatomia de pasta. Histórico sempre em versão com checkpoint.
Trocar o PO do projeto não muda o formato do artefato.
Fonte única: o manual Informações Portuárias — Terminais Aquaviários da Baía de Guanabara, 9ª edição, revisão 0.1, 2022, da própria Transpetro. Recorte decidido por quem conduziu: a troca de informações da estadia.
Um sistema para programar e acompanhar a estadia de um navio no terminal da Baía de Guanabara — do pedido de acesso até a autorização de descarga.
Hoje isso não é uma tela: é uma corrente de recados. A solução transforma a corrente num registro único da estadia, com estado visível, histórico e as travas que o manual já descreve.
Nenhuma regra foi escrita de cabeça. São 23 evidências do manual de 2022 ligadas a 5 requisitos e 22 critérios.
Onde o manual silencia, a especificação não preenche: fica registrado como ponto em aberto, para a Transpetro confirmar.
Como funciona hoje, segundo o manual
| Etapa | Quem participa | Como acontece |
|---|---|---|
| 1. Pedido | Quem representa a carga, e a Transpetro | Alguém pede o acesso do navio ao terminal. O manual registra que esse pedido existe, mas não descreve o que ele contém, por qual canal sai, nem em quanto tempo a resposta volta. |
| 2. Programação | Supervisor de turno, prático | O supervisor informa se a atracação consta da programação. Se não constar, o prático fundeia o navio e aguarda instruções. O terminal pode recusar atracação ou operação por inadequação, segurança, amarração ou risco a pessoas, equipamentos e meio ambiente. |
| 3. Chegada | Navio, agência, autoridades, GIAONT | O navio avisa o ETA ao agente com 72, 48 e 24 horas, em hora UTC, por telex, telefone ou rádio; alteração sai com no mínimo 12 horas. A agência repassa ao terminal, e o formulário segue por fax ou e-mail ao supervisor. A hora oficial é a passagem pela Ponta de Santa Cruz — fora da barra, vale o fundeio. Na manobra, o navio chama o terminal no VHF canal 16. O GIAONT inspeciona e condiciona o aceite do NOR. |
| 4. Descarga | Agência, programação da Transpetro, logística da Petrobras, GIAONT | Para slop, o agente informa quantidade e composição. A programação avalia os estoques com a logística da Petrobras e só autoriza se houver espaço nos tanques de terra. A transferência não começa antes da carta inicial, por terra e bordo, e da liberação do GIAONT — vale o que ocorrer por último. |
O que a solução passa a fazer
Quatro funcionalidades, uma por etapa. Todas derivadas do manual — e todas percorríveis no protótipo.
| Funcionalidade | O que o sistema faz | A trava que ele aplica |
|---|---|---|
| Registrar o pedido RF01 | O pedido vira um registro com terminal, navio e produto, consultável, marcando o início formal da estadia. Deixa de ser um recado solto. | Sem os três dados, não segue. Prazo e volume não são gravados, porque o manual não os define. |
| Responder a programação RN01 | Três respostas visíveis para quem pediu: a atracação consta; não consta, e o navio fundeia; ou a operação é recusada. A Transpetro pode alterar, e a mudança aparece no acompanhamento. | “Atracação consta” não é confirmação de berço. A recusa bloqueia chegada liberada e descarga. |
| Controlar ETA e chegada RF02 | Cada aviso vira registro com data, hora UTC, tipo e meio. A chegada oficial é outro registro, distinto do ETA: barra, ou fundeio quando o navio espera fora. O histórico fica completo. | Hora só local é recusada. Aviso novo não apaga os anteriores. A tela não confunde ETA com hora oficial. |
| Autorizar a descarga RN02 · RN03 | Só abre depois da chegada oficial. Para slop, exige quantidade, composição, espaço em terra e confirmação de estoque. Para os dois tipos, exige carta inicial, liberação do GIAONT e a troca de informações entre navio e terminal. | Faltando um desses, fica bloqueada — e o sistema não inventa volume. Carga comercial não herda os campos do slop. |
Em volta das quatro: dois acessos distintos — quem pede acompanha apenas a própria estadia; a Transpetro tem painel do que falta fazer, lista de pedidos e o quadro dos nove berços do terminal, agrupados nos seis píeres que o manual cita.
O que ficou em aberto, para a Transpetro confirmar
Não conversa com sistema da Petrobras: a confirmação de estoque é um registro, não uma consulta. Não calcula sozinho as 12 horas de antecedência. Não consulta disponibilidade real de berço. Não tem e-mail, rádio nem servidor: os registros vivem no navegador. E guarda uma estadia por vez.
Como demonstrar
Navio Exemplo, óleo combustível, no TABG. Atracação consta, berço em aberto, avisos de 72 e 48 horas, chegada oficial na barra, descarga ainda não feita.
Roteiro seguro: primeiro o acesso da Transpetro e suas telas, depois o do carregador acompanhando a mesma estadia. Não envie um pedido novo — ele substitui o exemplo. Qualquer senha entra; é demonstração, não o acesso real.
O que prometer, o que admitir, e como responder ao que vier.
Geração de valor — o que dá para afirmar
Um caminho só, da fonte até a spec, sem reescrever o artefato a cada mão que passa. O tempo que encolhe é o de entender e corrigir, antes da construção.
Não cite percentual. Não há ganho medido nos documentos deste projeto.
Requisito sem evidência não entra. Lacuna fica escrita em vez de preenchida. Todo requisito nasce com critério. Protótipo sem rastreio não vira spec.
O time recebe algo executável, não uma intenção.
Do processo: regra ambígua vira sistema plausível e errado. Definir acesso, exceção e escopo negativo na spec custa menos que refatorar depois do código gerado.
Segurança do terminal — GIAONT, recusa, tanque — é assunto do exemplo, não oferta da YouX.
Limites — dizer antes que perguntem
Se perguntarem
| Pergunta | Resposta |
|---|---|
| Vocês entregam a ferramenta? | A entrega é a especificação das regras, com um PO alocado. A Vyva fica no método da YouX. |
| Isso não é o Spec Kit? | Spec Kit começa na intenção escrita pelo engenheiro, dentro do repositório. A Vyva começa na fonte do cliente, com um PO responsável, e entrega um protótipo navegável para corrigir antes do código. |
| Substitui nosso pessoal? | Não. O PO conduz o recorte e a decisão. Quem confirma o que a fonte não diz é a Transpetro. |
| Qual o ganho? | Uma jornada rastreável, com o que o manual afirma separado do que ele não afirma, pronta para construir sem completar lacuna. Tempo e custo medidos não estão nos documentos. |
| E a alucinação? | Requisito sem evidência não entra no catálogo. Identificador e rastreio são determinísticos. Onde o protótipo finge uma garantia, o marcador de simulado aparece na tela. |
| E o desenvolvimento? | A regra desce até tarefa — registrar o pedido de acesso sem inventar prazo, volume ou nome de navio. A construção vem depois da regra aprovada. |
O que não dizer
1. Uma regra com origem no manual: sem espaço em tanque, o slop não é autorizado.
2. Um ponto em aberto: conteúdo, canal e prazo do pedido.
3. O relatório de honestidade, que mantém os 22 critérios como não verificados — é o que mostra que a ferramenta não enfeita resultado.