openclaw-refactor-docs

OpenClaw Refactor Docs

Visão Geral

Use esta habilidade quando o usuário fornecer uma página de documentação alvo do OpenClaw e pedir para reescrever, refatorar, reorganizar, dividir, encurtar ou melhorá-la.

Esta habilidade se baseia em technical-documentation: use essa habilidade para estilo, tipos de página, estrutura, exemplos, descoberta e verificação. Esta habilidade adiciona o fluxo de trabalho de reescrita necessário para evitar a perda de comportamento preciso durante uma grande refatoração de documentação.

Entradas

Obrigatório:

• Caminho da página de documentação alvo, como docs/plugins/codex-harness.md.

Opcional:

• Tipo de página desejado, como página de tópico, guia, referência ou solução de problemas.
• Objetivos específicos, como encurtar a página principal, mover detalhes para páginas de referência ou alinhar com o comportamento atual da CLI.
• Arquivos de origem relacionados, esquemas, comandos, testes, especificações ou PRs.

Se a página alvo estiver faltando ou for ambígua, faça uma pergunta concisa antes de editar. Caso contrário, prossiga.

Contrato de Trabalho

Refatore a página alvo para torná-la mais útil, concisa e abrangente dentro do escopo declarado.

Não trate uma reescrita como permissão para descartar fatos de comportamento. Preserve, verifique, mova ou retire explicitamente o material existente. Documentação incorreta é pior do que documentação prolixa.

Prefira esta divisão:

• Páginas de tópico ou guia cobrem o caminho 80/20, decisões que os leitores devem tomar, configuração segura, a menor verificação confiável, falhas comuns e links para frente.
• Páginas de referência cobrem campos exaustivos, padrões, enums, limites, regras de precedência, contratos de API, detalhes internos específicos e detalhes raros de depuração.
• Páginas de solução de problemas começam a partir de sintomas observáveis e mapeiam para verificações, causas e correções.

Fluxo de Trabalho

1. Carregar o padrão de documentação

Leia ../technical-documentation/SKILL.md primeiro. Aplique suas orientações de tipo de página, estilo, exemplos, navegação e verificação durante toda a refatoração.

Execute pnpm docs:list quando disponível, depois leia apenas a página alvo e os pontos de entrada prováveis, referências ou páginas relacionadas necessárias para a refatoração.

2. Classificar a página

Antes de editar, decida o tipo de página pretendido a partir de technical-documentation.

Se a página atual mistura tipos de página, escolha o tipo de página principal e planeie onde o outro material pertence:

• Mova contratos exaustivos para uma página de referência existente ou nova.
• Mova material orientado a sintomas para uma página de solução de problemas existente ou nova.
• Mova fluxos de trabalho de configuração restritos para um guia quando eles interromperem o caminho principal.
• Mantenha detalhes concisos de roteamento, decisão e segurança na página principal quando os leitores precisarem deles para concluir o fluxo de trabalho.

3. Preservar e auditar fatos existentes

Crie um inventário de trabalho a partir da página antiga antes de reescrever. Inclua:

• Campos de configuração, flags, comandos, comandos de barra, variáveis de ambiente, padrões, enums, valores anuláveis e restrições.
• Regras de precedência, comportamento de fallback, limites, caps, limites de taxa, tempos limite, estados de ciclo de vida, comportamento de fila e regras de compatibilidade.
• Comportamento de autenticação, permissão, aprovação, sandbox, segurança, privacidade e ação destrutiva.
• Requisitos de configuração, versões suportadas, dependências, sistemas operacionais, credenciais e requisitos de conta.
• Mensagens de erro, sintomas de solução de problemas, diagnósticos e etapas de recuperação.
• Exemplos, saída esperada, tabelas de roteamento de comandos e links cruzados.

Para cada fato, escolha um resultado:

• Mantê-lo na página alvo refatorada.
• Movê-lo para uma página existente específica.
• Movê-lo para uma nova página específica.
• Excluí-lo porque a fonte atual prova que está obsoleto ou fora do escopo.

Não infira padrões, permissões, políticas, comportamento de tempo limite ou postura de segurança a partir de nomes ou intenções. Verifique-os.

4. Encontrar a fonte da verdade

Use a fonte autoritativa mais próxima para cada afirmação sensível a comportamento:

• Esquema público, manifesto de plugin, documentação de configuração gerada ou tipos exportados para campos de configuração.
• Implementação da CLI, manipuladores de comandos de barra, texto de ajuda e testes de comando para comandos e flags.
• Código-fonte de tempo de execução e testes para comportamento de ciclo de vida, fila, permissão, fallback, tempo limite e provedor.
• Documentação de protocolo, fachadas de SDK e testes de contrato para APIs e superfícies de plugin.
• Documentação existente apenas como evidência secundária, a menos que o alvo seja puramente conceitual.

Se uma página prometer uma referência, compare suas tabelas com o esquema, manifesto, ajuda da CLI, documentação gerada ou tipos exportados. Campos públicos ausentes, padrões, regras de precedência, limites ou efeitos colaterais são bugs de correção.

5. Planejar o material movido

Ao mover detalhes para fora da página alvo, registre o destino antes de editar:

• Página existente: nomeie a página e a seção.
• Nova página: escolha o tipo de página, slug, título, resumo do frontmatter, doc-schema-version: 1 e dicas read_when.
• Página alvo: mantenha um resumo curto e um link a partir do ponto onde os leitores precisam do detalhe mais profundo.

Evite verdade duplicada. Se o mesmo contrato aparecer em vários lugares, escolha uma página canônica e faça um link para ela.

6. Reescrever

Reescreva nesta ordem:

1. Faça a primeira tela responder o que o leitor pode fazer e por que esta página existe.
2. Coloque o caminho recomendado antes das alternativas.
3. Mantenha apenas detalhes operacionais comuns e de tomada de decisão no fluxo principal.
4. Mova tabelas exaustivas e detalhes raros para as páginas de referência planejadas.
5. Preserve tabelas de roteamento concisas quando ajudarem os leitores a escolher comandos, caminhos de configuração, harnesses, plugins, provedores ou referências.
6. Adicione solução de problemas a partir de sintomas observáveis, não de palpites internos.
7. Faça links para conceitos relacionados, guias, referências, diagnósticos e ferramentas adjacentes.

Adicione doc-schema-version: 1 ao frontmatter YAML de cada página de documentação que a refatoração migrar, criar ou reescrever substancialmente. Aplique-o apenas a arquivos de página de documentação, não a docs.json ou outros metadados não pertencentes a página. Se uma página migrada for gerada, atualize o gerador para que a regeneração preserve o marcador em vez de editar manualmente a saída gerada.

Não deixe espaços reservados, como "TODO", "TBD" ou "veja a documentação", a menos que o usuário peça explicitamente um rascunho.

7. Comparar antigo e novo

Após editar, compare a página antiga e a nova:

• Confirme que todos os fatos sensíveis a comportamento foram mantidos, movidos ou excluídos intencionalmente com justificativa baseada em fonte.
• Verifique se a página principal ainda cobre o cenário 80/20 de ponta a ponta.
• Verifique se as páginas de referência permanecem exaustivas para o escopo que reivindicam.
• Verifique se os links da página alvo alcançam os detalhes movidos.
• Verifique se os cabeçalhos são estáveis, pesquisáveis e orientados a ação.

Se a refatoração remover deliberadamente material relevante, diga para onde ele foi ou por que foi removido no relatório final.

8. Verificar

Execute as verificações de documentação mais confiáveis e menores para a superfície tocada:

• pnpm docs:list
• git diff --check -- <arquivos-tocados>
• pnpm exec oxfmt --check --threads=1 <arquivos-tocados> direcionado
• pnpm docs:check-mdx
• pnpm docs:check-links
• Verificações de documentação gerada quando esquemas, documentação de configuração gerada, documentação de API ou linhas de base geradas forem tocadas

Execute comandos e exemplos da página sempre que possível. Se você não puder verificar uma afirmação sensível a comportamento, remova a afirmação, marque a incerteza no relatório de trabalho em andamento ou peça a fonte ausente.

Relatório Final

Relate:

• O que mudou na página alvo.
• Quais detalhes foram movidos e suas páginas de destino.
• Quais verificações de fonte da verdade apoiaram afirmações sensíveis a comportamento.
• Quais validações foram executadas e o que falhou por razões não relacionadas.

Não inclua um longo diário de reescrita. Lidere com riscos restantes apenas se houver algum.