openclaw-refactor-docs

OpenClaw Refactor Docs

Descripción general

Usa esta habilidad cuando el usuario proporcione una página de documentación de OpenClaw y solicite reescribirla, refactorizarla, reorganizarla, dividirla, acortarla o mejorarla.

Esta habilidad se basa en technical-documentation: usa esa habilidad para estilo, tipos de página, estructura, ejemplos, capacidad de descubrimiento y verificación. Esta habilidad añade el flujo de trabajo de reescritura necesario para evitar perder información precisa durante una refactorización importante de la documentación.

Entradas

Obligatorias:

• Una ruta de página de documentación de destino, como docs/plugins/codex-harness.md.

Opcionales:

• Tipo de página deseado, como página de tema, guía, referencia o solución de problemas.
• Objetivos específicos, como acortar la página principal, mover detalles a páginas de referencia o alinear con el comportamiento actual de la CLI.
• Archivos fuente relacionados, esquemas, comandos, pruebas, especificaciones o PRs.

Si la página de destino falta o es ambigua, haz una pregunta concisa antes de editar. De lo contrario, procede.

Contrato de trabajo

Refactoriza la página de destino para que sea más útil, concisa y completa dentro de su alcance declarado.

No trates una reescritura como un permiso para descartar hechos sobre el comportamiento. Preserva, verifica, mueve o elimina explícitamente el material existente. Una documentación incorrecta es peor que una documentación verbosa.

Prefiere esta división:

• Las páginas de tema o guía cubren el camino del 80/20, las decisiones que los lectores deben tomar, la configuración segura, la verificación mínima fiable, los fallos comunes y enlaces a más información.
• Las páginas de referencia cubren campos exhaustivos, valores predeterminados, enumeraciones, límites, reglas de precedencia, contratos de API, detalles internos específicos y detalles raros de depuración.
• Las páginas de solución de problemas comienzan a partir de síntomas observables y se asignan a comprobaciones, causas y soluciones.

Flujo de trabajo

1. Cargar el estándar de documentación

Lee primero ../technical-documentation/SKILL.md. Aplica su guía de tipo de página, estilo, ejemplos, navegación y verificación durante toda la refactorización.

Ejecuta pnpm docs:list cuando esté disponible, luego lee solo la página de destino y los puntos de entrada, referencias o páginas relacionadas probables necesarias para la refactorización.

2. Clasificar la página

Antes de editar, decide el tipo de página previsto según technical-documentation.

Si la página actual mezcla tipos de página, elige el tipo de página principal y planifica dónde pertenece el otro material:

• Mueve contratos exhaustivos a una página de referencia existente o nueva.
• Mueve material basado en síntomas a una página de solución de problemas existente o nueva.
• Mueve flujos de trabajo de configuración específicos a una guía cuando interrumpan la ruta principal.
• Mantén los detalles concisos de enrutamiento, decisión y seguridad en la página principal cuando los lectores los necesiten para completar el flujo de trabajo.

3. Preservar y auditar los hechos existentes

Crea un inventario de trabajo a partir de la página antigua antes de reescribir. Incluye:

• Campos de configuración, indicadores, comandos, comandos de barra diagonal, variables de entorno, valores predeterminados, enumeraciones, valores anulables y restricciones.
• Reglas de precedencia, comportamiento de respaldo, límites máximos, límites, límites de tasa, tiempos de espera, estados del ciclo de vida, comportamiento de colas y reglas de compatibilidad.
• Comportamiento de autenticación, permisos, aprobación, zona de pruebas, seguridad, privacidad y acciones destructivas.
• Requisitos de configuración, versiones compatibles, dependencias, sistemas operativos, credenciales y requisitos de cuenta.
• Mensajes de error, síntomas de solución de problemas, diagnósticos y pasos de recuperación.
• Ejemplos, salida esperada, tablas de enrutamiento de comandos y enlaces cruzados.

Para cada hecho, elige un resultado:

• Mantenerlo en la página de destino refactorizada.
• Moverlo a una página existente específica.
• Moverlo a una página nueva específica.
• Eliminarlo porque la fuente actual demuestra que está obsoleto o fuera del alcance.

No infieras valores predeterminados, permisos, políticas, comportamiento de tiempo de espera o postura de seguridad a partir de nombres o intenciones. Verifícalos.

4. Encontrar la fuente de verdad

Utiliza la fuente autorizada más cercana para cada afirmación sensible al comportamiento:

• Esquema público, manifiesto de plugin, documentación de configuración generada o tipos exportados para campos de configuración.
• Implementación de CLI, manejadores de comandos de barra diagonal, texto de ayuda y pruebas de comandos para comandos e indicadores.
• Código fuente y pruebas en tiempo de ejecución para el ciclo de vida, colas, permisos, respaldo, tiempo de espera y comportamiento del proveedor.
• Documentación de protocolo, fachadas SDK y pruebas de contrato para API y superficies de plugins.
• Documentación existente solo como evidencia secundaria a menos que el destino sea puramente conceptual.

Si una página promete una referencia, compara sus tablas con el esquema, manifiesto, ayuda de la CLI, documentación generada o tipos exportados. Los campos públicos faltantes, valores predeterminados, reglas de precedencia, límites máximos o efectos secundarios son errores de corrección.

5. Planificar el material movido

Al mover detalles fuera de la página de destino, registra el destino antes de editar:

• Página existente: nombra la página y la sección.
• Página nueva: elige el tipo de página, slug, título, resumen de frontmatter, doc-schema-version: 1 y sugerencias read_when.
• Página de destino: mantén un resumen breve y un enlace desde el punto donde los lectores necesiten el detalle más profundo.

Evita la verdad duplicada. Si el mismo contrato aparece en varios lugares, elige una página canónica y enlázala.

6. Reescribir

Reescribe en este orden:

1. Haz que la primera pantalla responda qué puede hacer el lector y por qué existe esta página.
2. Coloca la ruta recomendada antes que las alternativas.
3. Mantén solo los detalles operativos de toma de decisiones y comunes en el flujo principal.
4. Mueve tablas exhaustivas y detalles raros a las páginas de referencia planificadas.
5. Preserva tablas de enrutamiento concisas cuando ayuden a los lectores a elegir comandos, rutas de configuración, arneses, plugins, proveedores o referencias.
6. Añade solución de problemas a partir de síntomas observables, no de suposiciones internas.
7. Enlaza conceptos relacionados, guías, referencias, diagnósticos y herramientas adyacentes.

Añade doc-schema-version: 1 al frontmatter YAML de cada página de documentación que la refactorización migre, cree o reescriba sustancialmente. Aplícalo solo a archivos de páginas de documentación, no a docs.json, JSON de glosario u otros metadatos que no sean de página. Si una página migrada se genera, actualiza el generador para que la regeneración preserve el marcador en lugar de editar manualmente la salida generada.

No dejes marcadores de posición como "TODO", "TBD" o "ver documentación" a menos que el usuario solicite explícitamente un borrador.

7. Comparar versión antigua y nueva

Después de editar, compara la página antigua y la nueva:

• Confirma que todos los hechos sensibles al comportamiento se mantuvieron, movieron o eliminaron intencionalmente con una razón respaldada por la fuente.
• Verifica que la página principal aún cubra el escenario del 80/20 de principio a fin.
• Verifica que las páginas de referencia sigan siendo exhaustivas para el alcance que afirman.
• Verifica que los enlaces desde la página de destino lleguen a los detalles movidos.
• Verifica que los encabezados sean estables, buscables y orientados a la acción.

Si la refactorización elimina deliberadamente material relevante, indica dónde fue o por qué se eliminó en el informe final.

8. Verificar

Ejecuta las comprobaciones de documentación más pequeñas y fiables para la superficie modificada:

• pnpm docs:list
• git diff --check -- <touched-files>
• Ejecución específica de pnpm exec oxfmt --check --threads=1 <touched-files>
• pnpm docs:check-mdx
• pnpm docs:check-links
• pnpm docs:check-i18n-glossary cuando se haya modificado el texto del enlace, la navegación, las etiquetas o las superficies del glosario
• Comprobaciones de documentación generada cuando se hayan modificado esquemas, documentación de configuración generada, documentación de API o líneas base generadas

Ejecuta comandos y ejemplos de la página siempre que sea factible. Si no puedes verificar una afirmación sensible al comportamiento, elimínala, marca la incertidumbre en el informe de trabajo en progreso o solicita la fuente faltante.

Informe final

Informa:

• Qué cambió en la página de destino.
• Qué detalles se movieron y sus páginas de destino.
• Qué comprobaciones de fuente de verdad respaldaron las afirmaciones sensibles al comportamiento.
• Qué validación se ejecutó y qué falló por razones no relacionadas.

No incluyas un diario extenso de reescritura. Menciona los riesgos restantes solo si los hay.