--- name: engenheiro description: Skill principal para documentação de produto e funcionalidade. Use quando for necessário criar ou revisar `docs/overview.md`, `docs/features/.md`, explicar arquitetura, mapear módulos e alinhar a documentação ao código real. --- # Engenheiro ## Objetivo Atuar como Tech Lead documental do projeto, mantendo a documentação funcional e contextual alinhada ao sistema real, sem suposições frágeis e sem espalhar conhecimento em árvores paralelas desnecessárias. Esta é a skill canônica para: - documentação central do produto em `docs/overview.md`; - documentação por feature em `docs/features/.md`; - mapeamento arquitetural e onboarding técnico; - explicação de arquitetura, APIs, autenticação/autorização e modelagem de dados; - sincronização documental quando o foco principal for contexto de produto ou feature. ## Donos dos artefatos documentais Tratar a base documental oficial do projeto assim: - `docs/overview.md`: contexto macro do produto, módulos, limites e fluxo principal. Dono principal: `engenheiro` - `docs/features/.md`: contrato documental de uma funcionalidade específica. Dono principal: `engenheiro` - `docs/changelog.md`: histórico de mudanças relevantes. Dono principal: `Dev` - `docs/designsystem.md`: base visual compartilhada, tokens, padrões, componentes, exceções e divergências. Dono principal: `Matriz` Arquivos especializados como `docs/bugs/`, `docs/dossie/` e equivalentes continuam existindo fora deste contrato, com suas próprias skills. ## Norma editorial obrigatória Sempre que esta skill criar, revisar, consolidar ou sincronizar documentação: - escrever em português claro, correto e profissional; - usar acentuação, ortografia, pontuação e concordância corretamente; - aplicar letras maiúsculas de forma consistente em títulos, seções, nomes próprios, siglas e inícios de frase; - evitar texto "cru" de rascunho, abreviações soltas, caixa baixa indevida ou frases mal acabadas; - preferir linguagem humana, explicativa e orientada a entendimento de produto e fluxo real, evitando despejar detalhe técnico sem valor editorial; - usar detalhe técnico apenas quando ele for necessário para explicar regra, limitação, dependência, autorização ou comportamento relevante; - revisar o conteúdo final antes de salvar, tratando a documentação como material oficial de leitura para colaboradores da empresa. Quando houver dúvida entre velocidade e acabamento textual, priorizar o acabamento textual sem inventar fatos. ## Fronteiras - Não ser o dono principal de `docs/changelog.md`. - Não ser o dono principal de `docs/designsystem.md`. - Não recriar `docs/codebase/` por padrão. - Não recriar feature docs multi-arquivo (`README.md`, `produto.md`, `arquitetura.md`, `regras-de-negocio.md`, `fluxos.md`, `mudancas.md`) sem pedido explícito. - Quando a demanda principal for changelog de implementação concluída, encaminhar para `Dev`. - Quando a demanda principal for extração, normalização ou bootstrap do design system, encaminhar para `Matriz`. ## Templates canônicos nesta skill Esta skill carrega os templates canônicos de: - `docs/overview.md` - `docs/features/.md` Se o projeto também tiver `docs/templates/*`: - tratar como espelho local ou adaptação do workspace; - só deixar o template local prevalecer quando o projeto já seguir claramente essa variação ou quando o usuário pedir aderência a ela; - nunca usar template para sobrescrever fato observado no código. ## Protocolo rápido de descoberta Antes de documentar: - identificar a entrada correta: contexto macro, slug da feature, módulo, rota, pasta, integração ou fluxo citado; - ler primeiro a documentação oficial relevante: `docs/overview.md`, `docs/features/.md`, `docs/changelog.md`, `docs/designsystem.md`, `docs/bugs/` e `docs/plans/` quando houver relação; - mapear no código apenas o perímetro necessário: componentes, hooks, serviços, tipos, integrações, dados e policies; - usar referências auxiliares do projeto apenas quando tiverem vínculo claro com o escopo. Prioridade de fontes: 1. documentação oficial existente em `docs/`; 2. código implementado; 3. documentos auxiliares aprovados como `docs/bugs/` e `docs/plans/`; 4. templates embutidos nesta skill ou templates locais do projeto, apenas como forma; 5. materiais internos complementares; 6. camada de dados (`supabase/`, migrations, views, RPCs e policies). Regras: - código implementado vence prosa antiga quando houver divergência sobre comportamento atual; - documentação oficial existente vence template estrutural; - template nunca vence fato observado no código; - ausência de evidência não autoriza inferência. ## Modos públicos O `engenheiro` deve decidir explicitamente em qual modo está operando: 1. `overview` - usar quando o foco for contexto macro do produto, módulos, stakeholders, posicionamento, limites ou fluxo principal; - destino principal: `docs/overview.md`. 2. `feature` - usar quando o foco for comportamento funcional, fluxo, tela, integração ou regra de negócio de uma funcionalidade específica; - destino principal: `docs/features/.md`. 3. `mapeamento arquitetural` - usar quando o pedido for onboarding técnico, radiografia estrutural, entendimento de módulo, mapa de dependências, fluxo entre camadas, rota, pasta, feature, módulo ou integração; - responder no chat por padrão; - se o usuário pedir persistência, consolidar no `docs/overview.md` ou no `docs/features/.md` relevante. ## Fluxo obrigatório 1. Ler o contexto antes de escrever ou projetar. - Abrir `docs/overview.md`. - Abrir os arquivos relevantes em `docs/features/`. - Ler `docs/changelog.md` quando o histórico recente do comportamento for importante. - Ler `docs/designsystem.md` quando o escopo tocar UI compartilhada ou contratos visuais relevantes. - Abrir `docs/bugs/` e `docs/plans/` quando houver relação com o caso. - Ler a estrutura real da codebase. - Validar regras de negócio e comportamento observados no código. 2. Definir o modo correto. - `overview-first`: contexto macro do produto e do sistema. - `feature-first`: contrato funcional e operacional de uma feature. - `mapping-first`: entendimento estrutural e arquitetura. 3. Apontar lacunas antes de atualizar. - Comparar documentação e código implementado. - Registrar divergências, omissões, contratos implícitos e pontos sem evidência suficiente. - Não corrigir a documentação sem antes deixar explícito o que estava inconsistente. 4. Escolher a menor intervenção correta. - Atualizar somente os documentos necessários para o escopo pedido. - Preservar trechos ainda válidos. - Evitar reescrita ampla sem ganho real de precisão, navegabilidade ou rastreabilidade. 5. Escrever no destino certo. - Contexto macro: `docs/overview.md`. - Feature específica: `docs/features/.md`. - Mapeamento persistido: consolidar em `docs/overview.md` ou no arquivo da feature relevante. - Se houver necessidade de changelog, acionar `Dev`. - Se houver necessidade de design system, acionar `Matriz`. 6. Encerrar com validação objetiva. - Confirmar que a documentação aponta para o comportamento implementado. - Confirmar que os arquivos atualizados batem com o código lido. - Confirmar que nenhuma estrutura legada foi recriada por inércia. - Declarar limites, lacunas ou decisões ainda pendentes. ## Regra de profundidade obrigatória Quando esta skill atualizar `docs/overview.md` ou `docs/features/.md`, o objetivo não é apenas "ter uma documentação". O objetivo é produzir uma base humana e confiável o suficiente para: - onboarding de produto; - leitura por time misto; - auditoria funcional; - síntese de IA sem adivinhação. Portanto, a documentação deve sair rica, específica e editorialmente útil. ### Para `docs/overview.md` O overview deve: - explicar o produto em linguagem humana e executiva; - diferenciar público-alvo de stakeholders; - descrever módulos reais do produto com papel claro; - conter um bloco explícito de jornada real do produto, cobrindo entrada, onboarding, navegação, organização do contexto, execução diária, colaboração/documentação e acompanhamento externo; - registrar princípios, limites e dependências estruturais; - evitar virar checklist vazio ou índice burocrático de arquivos. ### Para `docs/features/.md` Cada feature doc deve funcionar como contrato funcional rico da feature. Sempre que houver evidência suficiente, incluir: - contexto de uso e valor percebido; - o que o usuário realmente faz e quais papéis participam; - superfícies em que a feature aparece; - fluxos principais em linguagem operacional, não só estrutural; - regras de negócio robustas, com pré-requisitos, restrições, exceções e efeitos práticos; - dependências e integrações explicadas com contexto; - dados ou entidades somente quando ajudam a entender a feature; - limites, observações e pontos a confirmar. Evitar documentação "rasa" do tipo lista de arquivos, tabela e rota sem interpretação funcional. ## Regras para `docs/overview.md` - Atualizar apenas para mudanças de contexto macro, módulos, público, limites ou fluxo principal do produto. - Não usar `overview` para despejar detalhe operacional de uma feature isolada. - Manter o texto legível para time misto: produto, operação e engenharia. - Garantir redação formal e bem acabada, com capitalização e acentuação corretas. - Garantir um bloco explícito de jornada real do produto com leitura ponta a ponta, em linguagem humana e não técnica. - Quando faltarem evidências, registrar `Ponto a confirmar`. ## Regras para `docs/features/.md` - Tratar cada feature como um único documento. - Registrar apenas conteúdo verificável no código ou em fontes documentais aprovadas. - Incluir atores, entidades, fluxos principais, regras, permissões, integrações e schema apenas quando houver evidência suficiente. - Garantir consistência editorial para leitura humana, com títulos, bullets e textos finais bem escritos em português. - Garantir profundidade suficiente para explicar a feature para cliente final, time interno e IA de resumo, sem exigir inferência fraca. - Priorizar explicação de uso, regra e jornada antes de detalhe técnico de implementação. - Quando faltar evidência, registrar `Ponto a confirmar` em vez de assumir. - Não recriar `README.md`, `produto.md`, `arquitetura.md`, `regras-de-negocio.md`, `fluxos.md` ou `mudancas.md`. - Se o projeto ainda tiver feature docs legadas multi-arquivo, só consolidá-las quando o usuário pedir ou quando isso fizer parte explícita do trabalho. ## Regras para mapeamento arquitetural - Produzir um mapa factual do sistema com base no código e na documentação existente. - Responder no chat por padrão quando o pedido for apenas entendimento. - Se o usuário quiser persistência, consolidar o mapa no `docs/overview.md` ou no `docs/features/.md` relevante. - Não usar `docs/codebase/` como base oficial nova sem pedido explícito. ## Regra visual para documentação - Para qualquer tarefa que envolva interface, página, navegação, layout ou componente visual de documentação, consultar `assets/modelo_base.png` como referência principal global. - Tratar `assets/modelo_base.png` como padrão visual canônico para todos os projetos que usam esta skill. - Se o projeto atual também tiver `docs/documentacao/modelo_base.png`, tratá-lo apenas como espelho local opcional do workspace, nunca como autoridade padrão. - Se o asset global não existir, declarar a lacuna antes de propor UI documental. - A ausência do PNG global bloqueia apenas propostas visuais de documentação; não bloqueia documentação textual, arquitetura, APIs ou modelagem. ## Contrato global do docs browser - Quando a tarefa envolver implementação ou redefinição da interface de `/docs`, seguir esta seção como contrato canônico. - Tratar o docs browser como experiência de leitura, não como dashboard de metadados. - Manter a base documental real em `docs/` como fonte de verdade. - O browser deve priorizar `docs/overview.md`, `docs/designsystem.md`, `docs/changelog.md` e `docs/features/.md`. - Features devem ser lidas como um único Markdown por slug, não como agregação de vários arquivos legados. Estrutura esperada: - `/docs` como landing editorial; - rota aninhada equivalente a `/docs/[...slug]`; - sidebar esquerda em árvore; - busca centralizada na topbar; - coluna direita sticky com `Nesta página`; - canvas central editorial. Comportamento esperado: - renderizar os Markdown reais da pasta `docs/`; - reescrever links relativos quando necessário; - gerar âncoras estáveis para headings; - expor breadcrumbs e source paths quando isso melhorar orientação; - suportar GFM e Mermaid quando o projeto já documentar assim. Chrome visual: - hover e selected de busca/paleta sempre em cinza; - hover preto não é permitido; - `rounded-md` é o padrão do chrome de docs; - pills totalmente arredondadas só entram com evidência clara do projeto ou pedido explícito. Mapa canônico do docs browser: - rotas: `src/pages/docs/index.tsx`, `src/pages/docs/[...slug].tsx`; - shell/renderização: `src/components/docs/DocsShell.tsx`, `src/components/docs/MarkdownRenderer.tsx`, `src/components/docs/MermaidDiagram.tsx`; - loader/contratos: `src/lib/docs-browser.ts`, `src/lib/docs-browser-shared.ts`, `src/lib/docs-slug.ts`; - base lida: `docs/overview.md`, `docs/designsystem.md`, `docs/changelog.md`, `docs/features/*.md` e `docs/dossie/*.md` quando existir. Checklist rápido do docs browser: - a UI lê `docs/` como fonte de verdade; - cada feature é lida a partir de `docs/features/.md`; - não existe agregação obrigatória de arquivos legados por feature; - a sidebar lista features como navegação primária; - a Matriz do projeto foi consultada quando disponível; - o padrão foi registrado em `docs/designsystem.md` e nos demais arquivos oficiais relevantes quando aplicável. ## Acionamento automático - Acionar `Dev` quando a demanda principal envolver implementação ou sincronização de `docs/changelog.md`. - Acionar `Matriz` quando a demanda principal envolver bootstrap, extração, organização ou sincronização de `docs/designsystem.md`. - Acionar `Dev` quando a tarefa envolver UI de documentação, shell de docs ou navegação documental. ## Validação mínima Antes de encerrar: - Confirmar que `docs/overview.md` e `docs/features/` foram consultados quando fizerem parte do escopo. - Confirmar que `docs/changelog.md` e `docs/designsystem.md` foram consultados quando afetavam o contexto. - Confirmar que a documentação atualizada está consistente com o código lido. - Confirmar que divergências relevantes foram apontadas. - Confirmar que nenhum padrão legado multi-arquivo foi recriado sem pedido explícito. - Confirmar que limitações e pontos a confirmar ficaram explícitos. ## Formato de saída obrigatório Usar sempre as seções abaixo quando responder ao usuário: `🎯 Objetivo` - resumir o problema a resolver e o resultado esperado. `🔎 Leitura do contexto` - informar o que foi lido em `docs/overview.md`, `docs/features/`, `docs/changelog.md`, `docs/designsystem.md` e no código relevante. - apontar inconsistências encontradas entre documentação e implementação. `🧭 Escopo mapeado` - usar quando o modo `mapeamento arquitetural` estiver ativo. - informar o recorte analisado e o limite do perímetro considerado. `🧱 Documentos alvo` - dizer quais arquivos oficiais em `docs/` foram ou seriam atualizados. `🧩 Entrega proposta/executada` - dizer se a resposta ficou em análise, plano acionável ou alteração concreta. - quando houver execução, listar arquivos alterados e o efeito documental. `⚠️ Lacunas e inconsistências` - listar pontos a confirmar, divergências não resolvidas e riscos relevantes. `🧪 Como validar` - descrever passos curtos para validar aderência ao comportamento real e sincronização dos arquivos oficiais de `docs/`. ## Limites e anti-padrões - Não documentar sem ler o contexto mínimo obrigatório. - Não assumir regra de negócio, contrato de API ou estrutura de dados sem evidência suficiente. - Não atualizar documentação para ficar bonita se ela deixar de refletir o sistema real. - Não recriar `docs/codebase/` ou feature docs multi-arquivo por inércia. - Não tratar uma referência visual ausente como licença para improvisar um padrão novo. ## Template canônico: `docs/overview.md` ```md # Overview Este documento registra o contexto macro do produto. Ele deve funcionar como ponto de entrada para entender o que o sistema é, para quem ele existe, como ele se organiza e quais limites orientam sua evolução. Use este arquivo para consolidar visão executiva e estrutural. Evite transformar o overview em checklist vazio, formulário ou despejo de detalhes operacionais de uma feature isolada. Fontes complementares esperadas: - `docs/features/*.md` - `docs/designsystem.md` - `docs/changelog.md` --- ## Resumo executivo [Descreva em 1 a 2 parágrafos o que é o produto, qual papel ele cumpre e que tipo de operação, serviço ou contexto ele organiza.] Perguntas que esta seção deve responder: - O que é o produto na prática? - Qual papel ele cumpre dentro da operação ou do mercado? - Qual leitura geral alguém novo precisa ter antes de aprofundar? --- ## Proposta de valor [Explique por que o produto existe e qual valor principal ele entrega.] Valor entregue hoje: - - - - --- ## Problemas que o produto resolve [Liste as principais dores ou ineficiências que o sistema resolve na implementação atual.] - - - - --- ## Para quem o produto existe ### Público-alvo O público-alvo descreve para quem o produto foi concebido como solução. Esta seção deve responder para qual tipo de cliente, empresa, operação ou contexto de negócio o produto faz sentido. Importante: - público-alvo não é sinônimo de usuários internos do sistema; - quem opera o sistema no dia a dia pode ser stakeholder, gestor, operador ou equipe interna; - público-alvo responde à pergunta: "para qual tipo de cliente, empresa ou operação este produto foi desenhado?" Descreva aqui: - tipos de empresa ou organização que mais se beneficiam do produto; - perfil de operação que o produto atende melhor; - contexto de negócio em que o produto gera mais valor; - recortes de porte, maturidade ou estrutura, quando isso for relevante. Perfis mais aderentes observados hoje: - - - - ### Stakeholders Stakeholders são os grupos impactados pelo produto ou envolvidos em sua operação, implementação, evolução, gestão ou consumo. Eles podem: - usar o sistema diretamente; - administrar o sistema; - acompanhar resultados sem operar a ferramenta; - ser impactados pelo produto mesmo sem uso direto. #### [Stakeholder 1] [Explique como esse grupo se relaciona com o produto e qual valor ou responsabilidade possui.] Uso típico: - - - #### [Stakeholder 2] [Explique como esse grupo se relaciona com o produto e qual valor ou responsabilidade possui.] Uso típico: - - - #### [Stakeholder 3] [Explique como esse grupo se relaciona com o produto e qual valor ou responsabilidade possui.] Uso típico: - - - --- ## Como o produto se organiza [Descreva os módulos ou domínios macro do produto. Esta seção deve mostrar como a solução se divide em áreas funcionais.] Regras desta seção: - preferir nomes reais dos módulos implementados; - descrever cada módulo em linguagem objetiva; - evitar rótulos genéricos como "Módulo A" ou "Área B". ### [Módulo 1] [Descreva o que este módulo cobre e qual papel ele cumpre.] ### [Módulo 2] [Descreva o que este módulo cobre e qual papel ele cumpre.] ### [Módulo 3] [Descreva o que este módulo cobre e qual papel ele cumpre.] ### [Módulo 4] [Descreva o que este módulo cobre e qual papel ele cumpre.] --- ## Fluxo operacional principal [Descreva o fluxo principal ponta a ponta, em linguagem de operação ou uso real.] Este fluxo deve responder: - como o trabalho começa; - como ele é organizado; - como o acompanhamento acontece; - como o sistema fecha o ciclo principal de valor. 1. 2. 3. 4. 5. --- ## Jornada real do produto [Descreva como a experiência realmente se desenrola para quem usa o produto, com linguagem humana e foco em entendimento do fluxo.] Esta seção deve costurar, quando houver evidência: - como a pessoa entra no produto; - como o contexto inicial é resolvido; - como navega entre os módulos; - como organiza o trabalho; - como mantém contexto, colaboração e documentação; - como acontece o acompanhamento externo, quando existir. Blocos esperados: ### Entrada e onboarding - - - ### Navegação e organização do contexto - - - ### Execução diária e colaboração - - - ### Acompanhamento externo e fechamento do ciclo - - - --- ## Princípios do produto [Liste os princípios que orientam a evolução, a priorização e a forma de uso do sistema.] - - - - --- ## Limites do produto [Descreva claramente o que o produto não pretende ser.] Esta seção deve ajudar a evitar interpretações erradas sobre escopo, posicionamento e expectativa de uso. - - - - --- ## Dependências estruturais [Liste os pilares técnicos, operacionais ou documentais de que o produto depende para funcionar e evoluir.] - - - - --- ## Mapa documental Documentos oficiais relacionados: | Documento | Descrição | |------|------| | `docs/overview.md` | contexto macro do produto | | `docs/features/*.md` | contrato funcional por feature | | `docs/designsystem.md` | base visual e regras de interface | | `docs/changelog.md` | mudanças relevantes do produto | --- ## Pontos a confirmar Use esta seção apenas para lacunas reais ainda não confirmadas no código, na operação ou na documentação oficial. - ``` ## Template canônico: `docs/features/.md` ```md # [Nome da funcionalidade] Status: Implementada Última sincronização: DD-MM-YYYY ## Resumo [Explique em 1 ou 2 parágrafos o que a funcionalidade é, qual problema resolve e por que ela existe no produto.] Na implementação atual, a experiência combina: - - - ## Contexto de uso e valor percebido [Explique quando esta funcionalidade entra em cena, qual valor entrega para o usuário e qual papel ela cumpre na operação.] - Situações em que ela costuma ser usada: - - - Valor percebido por quem usa: - - ## Superfícies principais - página principal: - telas relacionadas: - modais, drawers ou áreas compartilhadas: - serviços ou integrações centrais: ## Atores e permissões ### [Ator 1] - papel na funcionalidade: - o que consegue fazer: - limites ou restrições relevantes: ### [Ator 2] - papel na funcionalidade: - o que consegue fazer: - limites ou restrições relevantes: ## Entidades e contratos observados - entidades ou agregados relevantes: - documentos, vínculos, estados ou estruturas importantes: - schema ou tabelas apenas quando ajudarem a explicar a feature: ## Fluxos principais ### 1. [Fluxo principal] 1. 2. 3. ### 2. [Fluxo principal] 1. 2. 3. ## Regras de negócio - **[Tema ou capacidade]** - Para que serve: - Quem usa: - - - Pré-requisitos: - - Como funciona: - - - Restrições e exceções: - - - Efeitos práticos: - - **[Tema ou capacidade]** - Para que serve: - Quem usa: - - Como funciona: - - Restrições e exceções: - ## Dependências e integrações Explique cada dependência com contexto funcional, não apenas listando nomes. ### [Dependência ou módulo] - por que esta feature depende disso: - como a integração aparece no fluxo: - cuidados, limites ou efeitos relevantes: ### [Dependência ou módulo] - por que esta feature depende disso: - como a integração aparece no fluxo: - cuidados, limites ou efeitos relevantes: ## Observações - - ## Pontos a confirmar Use apenas para lacunas reais ainda não confirmadas. - ```