--- name: xpz-doc-builder description: Gera e atualiza documentação Markdown a partir de acervo XML GeneXus/XPZ e moldes sanitizados, usando scripts locais do repositório ativo --- # xpz-doc-builder Gera, recompõe e atualiza documentação Markdown a partir do acervo XML do repositório e de moldes sanitizados. Usa scripts locais do repositório ativo e evita depender de caminhos absolutos privados. --- ## GUIDELINE Identificar a raiz do repositório pelo contexto, localizar os scripts documentais em `scripts\`, resolver caminhos de entrada e saída a partir do cenário atual e delegar a geração ou atualização aos scripts apropriados. Evitar edição manual de `.md` longos quando houver fluxo automatizável. Se não houver script documental apropriado para o tipo de contrato, roteiro ou exemplo a registrar, edição manual pequena de Markdown é aceitável; a edição deve ser local, ancorada por seção, sem substituição ampla em `.md` longo, e seguida de releitura do início do arquivo, da seção alterada e da transição seguinte. Ao documentar acervo XML, distinguir snapshot oficial de artefato local de trabalho. Se a documentação depender da pasta paralela da KB e essa estrutura ainda não estiver montada ou validada, parar e usar `xpz-kb-parallel-setup` antes de gerar ou atualizar documentação. ## PATH RESOLUTION - Este `SKILL.md` fica dentro de uma subpasta de skill sob a raiz do repositório. - Toda referência `../arquivo.md` deve ser resolvida a partir da pasta deste `SKILL.md`, e não do diretório de trabalho corrente. - Na prática, `../` aponta para a base metodológica compartilhada na pasta-pai desta skill. --- ## TRIGGERS Use esta skill para: - Usuário quer gerar inventário documental da KB a partir do acervo XML - Usuário quer produzir documentação analítica ou matrizes a partir dos XMLs - Usuário quer recompor uma seção Markdown com moldes sanitizados completos - Usuário quer atualizar documentação a partir de exemplos reais de uma KB - Usuário quer manter a base documental que alimenta humanos e outras skills - Usuário quer gerar documentação a partir de fonte técnica validada do KB Intelligence, preservando a distinção entre evidência direta e inferência Do NOT use this skill for: - Sincronizar XMLs a partir de um XPZ exportado pela IDE (use `xpz-sync`) - Analisar um XML isolado sem intenção de atualizar a documentação (use `xpz-reader`) - Gerar ou clonar objetos XPZ para empacotamento (use `xpz-builder`) - Tratar o SQLite do KB Intelligence como fonte normativa no lugar dos XMLs oficiais - Localizar objetos no acervo da KB por nome ou tipo (usar `xpz-index-triage` primeiro quando houver índice KbIntelligence disponível) --- ## MODOS | Modo | Quando usar | |---|---| | `inventory` | Gerar inventário bruto do acervo XML | | `advanced-docs` | Produzir documentação analítica, matrizes e catálogos estruturais | | `update-section` | Recriar ou atualizar uma seção Markdown com exemplos XML completos | O KB Intelligence pode alimentar documentação em fase posterior, mas o índice SQLite é artefato derivado. Ao usá-lo, rotule a origem como índice técnico derivado e preserve links para XML oficial e evidência quando possível. --- ## SCRIPTS ESPERADOS O repositório deve conter em `\scripts\`: | Script | Papel | |---|---| | `generate-kb-inventory.ps1` | Gera inventário bruto da KB a partir do acervo XML | | `generate-kb-advanced-docs.ps1` | Gera documentação analítica a partir do acervo XML | | `Update-XpzDocSection.ps1` | Recompõe uma seção Markdown com exemplos XML e notas editoriais | Se o repositório ainda mantiver wrappers especializados, eles devem ser tratados como compatibilidade transitória, não como interface principal da skill. --- ## LOCALIZAÇÃO DO REPOSITÓRIO 1. Usar o diretório de trabalho atual como ponto de partida 2. Se necessário, subir até encontrar a raiz Git (`git rev-parse --show-toplevel`) 3. Localizar `scripts\` 4. Confirmar que os scripts documentais esperados existem 5. Se não existirem, relatar o problema antes de tentar alternativa manual --- ## PARÂMETROS COMUNS ### Geração de inventário - `-SourceRoot` *(obrigatório)* — raiz do acervo XML - `-OutputPath` *(obrigatório)* — arquivo Markdown de saída ### Geração analítica - `-SourceRoot` *(obrigatório)* — raiz do acervo XML - `-OutputRoot` *(obrigatório)* — pasta onde os Markdown serão gerados ### Atualização de seção - `-TargetMarkdown` *(obrigatório)* — arquivo Markdown a atualizar - `-SectionTitle` *(obrigatório)* — título exato da seção a recompor - `-IntroLines` *(opcional)* — linhas introdutórias da seção - `-XmlExamplePaths` *(obrigatório)* — lista de XMLs que serão incorporados - `-ExampleTitles` *(opcional)* — títulos por exemplo - `-ExampleNotes` *(opcional)* — notas por exemplo --- ## WORKFLOW 1. Identificar se o pedido é `inventory`, `advanced-docs` ou `update-section` 2. Se a pasta paralela da KB ainda não estiver montada, validada ou mapeada para este repositório → **ABORT** e usar `xpz-kb-parallel-setup` - Quando houver índice KbIntelligence disponível e a tarefa exigir selecionar ou localizar objetos do corpus para documentar, invocar `xpz-index-triage` antes de abrir XMLs para orientar a seleção 3. Resolver a raiz do repositório pelo contexto 4. Localizar `scripts\` e confirmar a existência do script adequado 5. Confirmar ou derivar caminhos de entrada e saída 6. Executar o script com parâmetros explícitos 7. Se usar casos de validação derivados do KB Intelligence, identificar primeiro o formato do caso antes de escolher o executor: - casos com `source`, `target` e `expected_rule` → validar no gerador/indexador com `Build-KbIntelligenceIndex.ps1 -ValidationCasesPath` - casos com `query` → validar no executor de consultas com `Test-KbIntelligenceQueries.ps1 -ValidationCasesPath` 8. Se a documentação citar XML vindo de `ObjetosGeradosParaImportacaoNaKbNoGenexus`, rotular isso como artefato de trabalho e não como snapshot oficial 9. Quando a documentação gerar ou preservar links de linha para XML GeneXus, rotular o papel do trecho citado: `Source efetivo`, `Rules/parm`, `metadado XML`, `chamada no chamador` ou `assinatura no chamado` 10. Se a documentação afirmar que objeto A chama objeto B, validar que o link de linha aponta para o `Source` efetivo de A ou para metadado explícito de chamada em A; linha de `parm(...)` em B deve ser descrita apenas como assinatura do chamado 11. Se usar saída do KB Intelligence, declarar que a fonte imediata é índice técnico derivado e que a fonte normativa continua sendo o XML oficial em `ObjetosDaKbEmXml`; quando houver evidência citada, preservar referência ao XML oficial, papel do trecho citado e nível de confiança 12. Quando a documentação tiver natureza funcional, separar explicitamente `Evidência direta`, `Leitura adicional do XML`, `Inferência forte` e `Hipótese` 13. Reler o início do arquivo gerado ou alterado, a seção modificada e a transição seguinte 14. Reportar o que foi criado, atualizado ou substituído --- ## CONSTRAINTS - NUNCA assumir caminhos absolutos privados - NUNCA gerar documentação operacional dependente da pasta paralela da KB enquanto essa estrutura ainda estiver indefinida ou não validada - NUNCA editar `.md` longos manualmente se houver script apropriado - NUNCA reescrever uma seção sem identificar corretamente o título-alvo - NUNCA esconder que o conteúdo foi gerado a partir de XMLs sanitizados ou acervo real quando isso for relevante - NUNCA tratar `ObjetosGeradosParaImportacaoNaKbNoGenexus` como se fosse snapshot oficial da KB sem rotulagem explícita - NUNCA editar `ObjetosDaKbEmXml` esperando que a documentação ou o empacotamento use essa versão; o acervo é somente leitura para agentes (ver `02-regras-operacionais-e-runtime.md`, anti-padrão "editar acervo esperando que o pacote pegue") - NUNCA documentar uma linha de `parm(...)` do objeto chamado como se fosse o ponto de chamada no objeto chamador - NUNCA tratar o SQLite do KB Intelligence como prova funcional ou runtime; ele é índice técnico derivado de evidências extraídas - NUNCA escolher o executor de validação do KB Intelligence só pelo nome da fase; o formato do caso (`expected_rule` versus `query`) é que define o executor compatível - Se o script esperado não existir, reportar o problema antes de improvisar uma edição manual ampla