zehuichan/vibe-harness

Estándar de documentación

Haz que cada página sea buscable, legible para principiantes y lo suficientemente precisa para agentes y mantenedores. Los niveles, reglas de redacción, presupuestos y la lista de control de 'slop' residen en docs/AGENTS.md; este skill posee el flujo de trabajo para aplicarlos. Conserva un único propietario por hecho: fuente, pruebas, catálogos generados, READMEs, guías y Notas de Agente mantienen cada uno su propio tipo de verdad. Esto es una guía, no una lista de control.

Flujo de trabajo

Sigue esta secuencia para cada alcance solicitado. Mantén breve la ruta común del lector, pero no elimines fallos, propiedad, limitaciones u otros contratos requeridos para reducir palabras.

1. Lee los archivos AGENTS.md raíz y del subárbol, docs/AGENTS.md, la página objetivo, su fuente y pruebas, y su propietario de navegación.
2. Clasifica la página por un trabajo principal y lector: inicio rápido, guía de tareas de usuario, tutorial de colaborador, visión general de arquitectura, referencia de módulo, referencia generada, instrucción de agente, registro de decisión o borrador.
3. Coloca la página en su propietario más cercano. Mantén los contratos del módulo junto al código del módulo; usa docs/ para material de aprendizaje, usuario, desarrollador y arquitectura entre módulos.
4. Define el estado inicial del lector, el resultado observable, el posible fallo, la ruta de recuperación y la siguiente profundidad útil antes de escribir los detalles.
5. Escribe en el orden dado por estructura de página: título, Resumen, contenido, contenido orientado al usuario, contenido orientado al desarrollador, opcional Exploración adicional.
6. Cuando el perfil habilite surfaces.bilingual-docs, actualiza la contraparte en la misma pasada y mantén encabezados, listas, tablas, código y enlaces alineados línea por línea.
7. Verifica cada afirmación contra el código, las pruebas, los generadores, los metadatos del paquete o un propietario de decisión actual, y ejecuta las operaciones que la página instruye (consulta el procedimiento de verificación de hechos a continuación). Actualiza el propietario antes de cualquier artefacto derivado.
8. Ejecuta commands.docs-check y git diff --check del perfil, luego vuelve a leer el diff completo una vez para verificar corrección y otra para brevedad y ajuste.

Procedimiento de verificación de hechos: prueba, no asumas

La documentación describe cómo se comporta el producto hoy, y la única evidencia admisible para una afirmación de operación es haberla ejecutado. Esto aplica a cada página nueva y cada párrafo nuevo que afirme un comando, valor predeterminado, error, salida o diferencia de plataforma.

1. Clasifica el tema antes de escribir guías de instalación o uso. Lee los hechos (manifiestos, puntos de entrada, exportaciones), no el nombre de la carpeta. Una biblioteca, un plugin, una CLI y un servicio tienen cada uno una ruta de uso diferente; nunca copies una guía escrita para otro tipo.
2. Ejecuta cada operación afirmada contra el checkout actual. Ejecuta cada comando, fragmento de configuración y ejemplo exactamente como aparecerá en la página; escribe solo lo que observaste, incluyendo advertencias y modos de fallo. Si una afirmación depende de credenciales o una red que no tienes, dilos y nombra al propietario de verificación en lugar de afirmar el comportamiento.
3. Elimina lo que no pudiste reproducir. Nunca arrastres un comando, campo, valor predeterminado o comportamiento de la memoria, analogía o un README vecino. Cuando una afirmación falla al reproducir, corrige la afirmación, no la prueba.
4. Revisa documentación antigua contra la última rama predeterminada. Antes de revisar una página existente, obtén y compara con la rama predeterminada; corrige afirmaciones obsoletas contra el código, no contra la prosa antigua.

Reglas de redacción

• El Resumen dice qué hace el tema. El Resumen y las secciones orientadas al usuario describen qué puede hacer un lector con el tema (resultados, cuándo elegirlo, costo principal), nunca su identidad interna o registros. Omite identificadores de fuente a menos que el lector los use directamente en configuración, un comando o una API pública.
• Las secciones de desarrollador explican, nunca enumeran. El detalle de desarrollador cubre el concepto de diseño, la arquitectura y el flujo de datos aproximado, suficiente para entender cómo funciona, y enlaza al código para detalles exactos. Sin catálogos completos de API, listas de columnas o reafirmación de documentación de API.
• Solo estado actual. La documentación ordinaria describe el código base actual; el historial pertenece a Notas de Agente, autopsias, notas de lanzamiento y guías de actualización.
• Inglés técnico controlado. Dale a cada oración un actor explícito y una acción principal cuando la ambigüedad pueda cambiar el comportamiento; reutiliza un término por concepto; divide instrucciones apiladas; preserva modalidad y excepciones. Consulta estructura de página.

Criterios de calidad

• Breve: la ruta común contiene solo los hechos necesarios para su resultado; la verdad exhaustiva está a un enlace o capa de detalle de distancia.
• Intuitivo: los prerrequisitos preceden a los conceptos dependientes, una siguiente acción es obvia y los encabezados usan términos que los lectores buscan.
• Amigable: los lectores pueden reconocer el éxito, entender el riesgo antes de actuar, recuperarse de un posible fallo y elegir si profundizar.
• Preciso: cada afirmación duradera tiene un propietario y una ruta de verificación proporcionada a su riesgo.
• Legible por agentes: encabezados estables, anclas, terminología y propiedad respaldan la recuperación dirigida sin cargar todo el corpus.
• Completo para principiantes: un ingeniero sin contexto del repositorio puede reconstruir la arquitectura o función relevante a través de tres a cinco páginas enlazadas.

No apliques un límite universal de palabras a referencias exhaustivas; mide la longitud de la ruta de entrada, material no relacionado escaneado por búsqueda y la sección más grande, y divide por un propietario de dominio existente cuando el costo de recuperación sea alto.

Audita el corpus

Aplica el orden de autoría de docs/AGENTS.md a cada documento orientado a humanos en alcance (no a Notas de Agente): localiza el documento y declara su tema; establece su detalle permitido y mueve explicaciones más profundas a descendientes propietarios; clasifica tutorial o referencia según el uso previsto, no la ruta; divide formas mixtas sustanciales. Un movimiento es atómico con cada enlace entrante reparado en el mismo cambio; los catálogos generados nunca se editan a mano.

Luego busca la lista de control de 'slop' en docs/AGENTS.md, comenzando por las sondas más baratas: usa trim-cot-leakage para fugas de transcripción de razonamiento, busca frases distintivas para reglas duplicadas, reemplaza catálogos escritos a mano por sus propietarios autoritativos y elimina lenguaje de especificaciones de Notas de Agente implementadas. Si eliminar prosa cambiara el comportamiento prometido en lugar de su explicación, propón primero el cambio de comportamiento (consulta find-simplifications). Mantén cada regla importante, preferiblemente como una a tres líneas más un enlace a su fundamento.

Referencias detalladas

• Estructura y estilo de página: orden de página, progresión de secciones, plegado, inglés técnico controlado y énfasis.
• Criterios de revisión: la prueba del principiante, revisión de evidencia y revisión de README.

Usa prose-standard para cobertura de contratos a nivel de oración y criterio editorial.