sirius-zuo/generate-wiki

Visão Geral

Constrói uma wiki de arquitetura interna: uma página markdown por subsistema (arquitetura, fluxos de execução, decisões-chave rastreáveis por PR, âncoras de código-fonte), conectadas por um README.md central e um script de verificação mecânica. Dois modos: generate constrói uma wiki do zero; refresh detecta desvios via as Âncoras de Código-Fonte de cada página e atualiza apenas o que mudou. Abaixo, <skill>/ se refere ao diretório desta própria habilidade (onde este arquivo, references/, e assets/ residem) — distinto de <dir>, o diretório de saída da wiki no repositório alvo. Antes de fazer qualquer outra coisa, crie uma lista de tarefas: um item para cada etapa numerada do modo ativo (G1–G7 ou R1–R3), assim que a Etapa 0 determinar qual modo está ativo.

Etapa 0 — Analisar argumentos e detectar modo

$ARGUMENTS começando com refresh → modo refresh; qualquer outra coisa (incluindo vazio) → modo generate. Dos argumentos restantes, extraia e registre: --dry-run (apenas refresh), --pages a,b (restringe o refresh às páginas nomeadas), --dir <caminho> (diretório da wiki, padrão wiki). No modo refresh, se <dir>/README.md não existir, pare e informe ao usuário para executar generate primeiro — não há nada para atualizar.

Generate G1 — Pré-verificação

Verifique: o diretório atual está dentro de um repositório git; a ferramenta Agent está disponível. Se a árvore de trabalho estiver suja, use AskUserQuestion para confirmar antes de prosseguir — nunca presuma. Teste capacidades: gh auth status define se a camada de origem de corpos de PR (regras de vinculação §2) existe nesta execução. Verifique a existência de diretórios de documentos de design na raiz do repositório — docs/, doc/, design/, adr/, rfcs/ — apenas existência; qual(is) minerar será confirmado em G2. Crie o branch de trabalho (padrão docs/internal-wiki, nome confirmado em G2) e registre git rev-parse HEAD > .generate-wiki/branch-base (G6 lê isto para o diff de todo o branch). Garanta que .generate-wiki/ esteja listado no .gitignore do repositório alvo, adicionando-o se não estiver — este diretório de estado de execução (registro, briefings, relatórios, pacotes de diff) nunca deve ser commitado.

Generate G2 — Entrevista

Antes de fazer qualquer pergunta, derive automaticamente uma proposta de conjunto de páginas: enumere subsistemas a partir de manifestos de workspace/pacote, ou diretórios de código-fonte de nível superior se o ecossistema não expuser manifestos, e proponha uma página por subsistema com uma nota de "abrange" de uma linha. Em seguida, execute exatamente UMA rodada de AskUserQuestion, com até 3 perguntas:

1. Aprovar ou ajustar o conjunto de páginas proposto (mesclar, dividir, adicionar, remover).
2. Confirmar o diretório de saída (<dir>) e o nome do branch — se o usuário escolher um nome diferente do padrão de G1, renomeie o branch com git branch -m <novo-nome>.
3. Confirmar as entradas de origem: quais diretórios de documentos de design minerar (e se eles são rastreados) e se o histórico de PRs é significativo aqui.

Após esta rodada, a execução é totalmente autônoma — nenhuma pergunta adicional no modo generate.

Generate G3 — Estrutura inicial

Materialize os três ativos no repositório alvo:

• assets/TEMPLATE.md → <dir>/TEMPLATE.md, copiado como está.
• assets/hub-template.md → <dir>/README.md, com todos os quatro tokens {{...}} preenchidos: {{PROJECT_NAME}}; {{SYSTEM_DESCRIPTION}} (dois parágrafos redigidos a partir da exploração do repositório); {{CRATE_DAG}} — grafo graph TD mermaid derivado de dependências reais de manifesto, nunca inventadas; os IDs dos nós devem evitar palavras reservadas do Mermaid conforme references/binding-rules.md (uma crate abreviada para graph, end, etc. quebra a renderização — renomeie o ID, mantenha o nome da crate no rótulo); {{PAGE_INDEX}} — uma tabela | Página | Abrange | Resumo |, uma linha por página aprovada, com resumos provisórios (finalizados em G5).
• assets/check-wiki.sh.tmpl → scripts/check-wiki.sh modo 0755 (ou <dir>/check-wiki.sh se o repositório não tiver uma convenção scripts/), renderizado com o comando exato:

  sed -e "s|{{CANONICAL_PAGES}}|$PAGES|g" -e "s|{{WIKI_DIR}}|$DIR|g" <skill>/assets/check-wiki.sh.tmpl > scripts/check-wiki.sh
  

  onde $PAGES são os nomes de arquivo das páginas aprovadas separados por espaço e $DIR é <dir>. Chame o caminho deste script renderizado de $CHECK para o restante deste documento — invoque como $CHECK [pagina.md ...] (sem argumentos verifica todas as páginas exceto README/TEMPLATE; argumentos nomeados verificam apenas essas páginas).

Um commit: estrutura inicial.

Generate G4 — Loop por página

Sequencial — uma página de cada vez, nunca em paralelo: o commit de cada página torna-se o contexto do git log para a próxima página, e a execução paralela arrisca duas páginas colidirem no mesmo link cruzado ou escolha de terminologia. Para cada página aprovada <nome> (arquivo <nome>.md):

a. Explore e componha o briefing em BRIEF_PATH = .generate-wiki/page-<nome>-brief.md: uma tabela de fontes (diretórios/módulos cobertos, documentos de design a minerar, PRs/commits de git log --oneline -- <dirs> mais gh pr list quando disponível), fluxos mínimos, decisões mínimas. Briefings são pisos, não tetos. b. Registre BASE=$(git rev-parse HEAD). c. Dispache um subagente implementador em um modelo de nível médio (no Claude Code: sonnet) a partir de references/page-implementer.md, preenchendo todos os sete slots: <<BRIEF_PATH>> = o briefing de (a); <<WIKI_DIR>> = <dir>; <<PAGE_FILE>> = <nome>.md; <<STYLE_REF>> = o nome do arquivo da página anterior, ou a string literal "nenhum — você está escrevendo a primeira página" para a primeira página; <<CHECK_CMD>> = $CHECK <nome>.md; <<BINDING_RULES>> = o conteúdo completo e literal de references/binding-rules.md; <<REPORT_PATH>> = .generate-wiki/report-<nome>.md. d. Gere o pacote de diff: git diff $BASE..HEAD > .generate-wiki/review-<nome>.diff — este caminho é DIFF_PACKAGE_PATH. e. Dispache um subagente revisor em um modelo de nível médio (no Claude Code: sonnet) a partir de references/page-reviewer.md, preenchendo todos os seis slots: <<BRIEF_PATH>> = mesmo briefing de (a); <<REPORT_PATH>> = o relatório do implementador de (c); <<DIFF_PACKAGE_PATH>> = o diff de (d); <<BINDING_RULES>> = references/binding-rules.md literal; <<MIN_COVERAGE>> = os fluxos e decisões mínimos do briefing, reafirmados inline; <<CHECK_CMD>> = mesmo valor que (c). f. Constatações Críticas/Importantes → dispache UM subagente de correção em um modelo de nível médio (no Claude Code: sonnet) com a lista completa de constatações e as regras de vinculação, anexando ao mesmo REPORT_PATH; regenere o pacote de diff com git diff $BASE..HEAD > .generate-wiki/review-<nome>.diff; em seguida, redispache o revisor com os mesmos slots. Constatações Menores → registre no registro para triagem na revisão final; não corrija agora. g. Acrescente uma linha a .generate-wiki/progress.md: Página <nome>: completa (commits X..Y, revisão <resultado>); menores: ...; constatações: ....

Recuperação de falhas: na invocação, leia .generate-wiki/progress.md primeiro. As páginas que ele marca como completas são ignoradas — nunca regenere uma página que o registro indica como completa. Uma página com um rascunho não commitado (git status mostra o arquivo da página) é retomada: redispache a partir da Etapa D (Verificação) do procedimento do implementador em diante.

Generate G5 — Passagem de links cruzados

Dispache UM subagente em um modelo de nível médio (no Claude Code: sonnet) a partir de references/cross-linker.md, uma vez, depois que todas as páginas forem implementadas e revisadas, preenchendo todos os quatro slots: <<WIKI_DIR>> = <dir>; <<CHECK_CMD>> = $CHECK (sem argumentos de página, verifica todas as páginas); <<BINDING_RULES>> = references/binding-rules.md literal; <<REPORT_PATH>> = .generate-wiki/cross-link-report.md. Em seguida, o orquestrador verifica diretamente — sem dispache de revisor para esta passagem: $CHECK verde em todas as páginas; uma nova varredura de grafo de links simétricos (re-executada, não reutilizada do relatório do subagente); zero caminhos soltos de documentos de design; verificação pontual de qualquer nova frase que a passagem introduziu contra a fonte.

Generate G6 — Revisão final

Construa o pacote de diff de todo o branch: git diff <branch-base>..HEAD > .generate-wiki/final-diff.diff (<branch-base> = o conteúdo de .generate-wiki/branch-base, registrado em G1). Escreva .generate-wiki/triage.md: cada Menor adiado mais cada constatação de projeto real registrada no registro. Dispache UM subagente em o modelo mais capaz disponível a partir de references/final-reviewer.md, preenchendo todos os cinco slots: <<WIKI_DIR>> = <dir>; <<CHECK_CMD>> = $CHECK; <<DIFF_PACKAGE_PATH>> = .generate-wiki/final-diff.diff; <<LEDGER_PATH>> = .generate-wiki/progress.md; <<TRIAGE_PATH>> = .generate-wiki/triage.md. Esta é uma revisão somente leitura — não deve tocar na árvore de trabalho. Para suas constatações, dispache UM subagente de correção em um modelo de nível médio (no Claude Code: sonnet) cobrindo a lista completa (o orquestrador pode aplicar correções de frase única diretamente). Reexecute todas as verificações — $CHECK verde em todas as páginas, uma varredura de grafo de links simétricos, e zero caminhos soltos de documentos de design — após as correções serem aplicadas.

Generate G7 — Entrega

Reexecute todas as verificações uma última vez. Resuma para o usuário: páginas construídas, o resultado da revisão de cada página e — como um resultado de primeira classe, não um aparte — a lista de constatações de projeto reais (código morto, funcionalidades não conectadas, comentários desatualizados, desvio de especificação) reveladas durante a execução, com uma sugestão para abrir tickets de acompanhamento. Ofereça-se para enviar o branch e abrir um PR; nunca execute nenhum dos dois sem a confirmação explícita do usuário.

Refresh R1 — Detecção de desvio

Pré-verificação: exija uma árvore de trabalho limpa — se estiver suja, use AskUserQuestion para confirmar antes de qualquer edição R3; os commits de refresh caem no branch atual, não em um novo.

Para cada página em <dir>, exceto README.md e TEMPLATE.md (ou apenas o subconjunto --pages, se fornecido): analise sua seção de Âncoras de Código-Fonte em uma lista de caminhos. LAST=$(git log -1 --format=%H -- <dir>/<pagina>). git log --oneline $LAST.. -- <caminhos-ancora> não vazio → desviou. Um caminho de âncora que não existe mais no disco → desvio duro, sinalizado separadamente. Uma âncora que não pode ser analisada como um caminho → não atualizável: relate o problema de análise para essa página em R2, não adivinhe o que significava.

Refresh R2 — Relatório / parada dry-run

Emita uma tabela de desvios: página → commits desviantes (com assuntos) → âncoras de desvio duro → notas não atualizáveis. --dry-run encerra a execução aqui — a árvore de trabalho não é tocada, nada é commitado.

Refresh R3 — Loop de atualização

$CHECK aqui é o script de verificação materializado — scripts/check-wiki.sh ou <dir>/check-wiki.sh, o que existir. Para cada página desviada (páginas não desviadas são completamente ignoradas), execute a mesma maquinaria G4 (etapas a–g, mesmo preenchimento de slots, mesma verificação de revisor) com duas alterações: o briefing é um briefing de refresh — a evidência de desvio de R1 (os commits/PRs que tocaram nas âncoras da página, mais corpos gh pr view quando disponíveis) — em vez de uma tabela de fontes do zero; e o implementador segue regras específicas de refresh sobrepostas às regras de vinculação: atualize apenas o que realmente mudou; novas entradas de Decisão Chave são adicionadas primeiro a mais recente; NUNCA reescreva ou exclua uma entrada de decisão existente — ela é histórico; atualize as Âncoras de Código-Fonte para caminhos que foram movidos; documente a funcionalidade removida honestamente em vez de excluir seu registro. Execute a verificação de links cruzados (G5, apenas verificação mecânica) apenas para páginas cujo conjunto de links mudou. Um commit por página atualizada.

Seleção de modelo

Implementadores de página, revisores de página, subagentes de correção e o vinculador cruzado são dispachados em um modelo de nível médio (no Claude Code: sonnet). A revisão final de toda a wiki (G6) é dispachada em o modelo mais capaz disponível. O orquestrador nunca herda seu próprio modelo de sessão em um dispache implicitamente — cada chamada Agent acima nomeia seu modelo explicitamente.

Tratamento de erros

• Subagente morre no meio da tarefa: o trabalho é recuperável — páginas commitadas estão no git, .generate-wiki/progress.md as nomeia; um rascunho não commitado é encontrado via git status e retomado. Nunca regenere uma página que o registro marca como completa.
• Nenhum gh / não autenticado: a origem degrada de acordo com as regras de vinculação §2 (documentos de design → arqueologia de commit → a redação alternativa); a geração prossegue sem corpos de PR.
• Script de verificação falha dentro de uma tarefa de página: o implementador o corrige em sua própria Etapa D (Verificação) antes de commitar; uma falha que atinge o orquestrador (a etapa f de G4 já foi executada uma vez) é um gatilho de ciclo de correção, não uma falha.
• Árvore suja na pré-verificação: pergunte, não presuma (G1).
• Âncoras de código-fonte malformadas durante refresh: sinalize como não atualizável (R1); nunca adivinhe o caminho pretendido.