zehuichan/vibe-harness

Notas de Agente

Las Notas de Agente mantienen el corpus de decisiones pequeño y autoritativo: cada nota registra la justificación que el código y la documentación no pueden transmitir, y nada más. Las reglas sobre diseño, clases y el formato dentro del archivo están en .agents/notes/README.md; este skill posee el flujo de trabajo. Evalúa cada nota semánticamente; el recuento de palabras y la antigüedad son ayudas para el descubrimiento, nunca criterios. Esto es una guía, no una lista de verificación.

Decidir si una nota es necesaria

Escribe o actualiza una nota solo para justificaciones de decisiones duraderas: por qué ganó un diseño, qué sacrificó, qué alternativas perdieron y por qué, y qué verificación lo respalda. No escribas una para cambios mecánicos o locales, incluyendo cambios locales en la presentación de la interfaz de usuario, o para hechos que pertenecen al código, la documentación de la API, los README o un libro de recetas.

• Una propuesta para trabajo futuro sustancial va a proposed/<class>/; una decisión tomada en el cambio actual va a implemented/<class>/.
• Si una nota activa ya cubre la decisión, actualízala en lugar de crear un duplicado.
• Una reversión de una decisión es una nota nueva que enlaza la anterior; nunca edites una nota para convertirla en una decisión diferente.

Escribir la nota

1. Elige la clase de la tabla en .agents/notes/README.md y nombra el archivo aaaa-mm-dd-tema-titulo.md, usando la fecha en que el tema se propuso por primera vez.
2. Usa el encabezado exacto y el esqueleto de la sección del ciclo de vida del README. ## Alternativas consideradas es obligatorio: registra cada alternativa genuina y por qué perdió; nunca inventes alternativas.
3. Escribe las notas implementadas en tiempo presente como realidad enviada: sin planes, listas de verificación de aceptación o "debería". Mantén la verificación que fija el comportamiento y cualquier brecha de cobertura nombrada.
4. Enlaza otras notas y documentos con enlaces Markdown relativos. Sigue prose-standard y trim-cot-leakage: sin coreografía de revisión, citas de sesión ni narración de cambios fuera de las secciones de historial de cambios de la propia nota.

Verificar el reemplazo de cada nota nueva

Antes de redactar, busca en el árbol activo (proposed/, implemented/, rejected/) notas que cubran la misma decisión, mecanismo o alternativa rechazada. Clasifica cada coincidencia mientras escribes la nota nueva:

• Reemplazo completo de una nota implementada: consolida (la nueva nota conserva toda justificación única, alternativa, consecuencia, verificación y brecha de cobertura, luego la nota antigua se elimina y se reparan los enlaces entrantes) o archívala en el mismo cambio.
• Reemplazo parcial: mantén ambas activas, enlázalas y actualiza cada hecho que siga siendo actual.
• Propuesta obsoleta: muévela a rejected/ con una razón honesta de una línea.
• Rechazo obsoleto: elimínalo cuando ya no prevenga un error plausible.

No difieras una coincidencia conocida a una auditoría posterior.

Clasificar notas existentes por valor futuro

Al auditar o podar, aplica estos resultados por ciclo de vida:

• Implementada, eliminar: notas que solo describen pequeños ajustes de UI o cambios puramente mecánicos. Repara o elimina los enlaces entrantes. Las correcciones de errores locales, cambios de rendimiento, nuevas capacidades y decisiones sustanciales de comportamiento o propiedad no califican simplemente porque su implementación fue pequeña. Aplica esta prueba antes de conservar o archivar.
• Implementada, mantener activa: justificaciones, alternativas, garantías negativas, semántica de cable o wire, límites de propiedad, reglas de seguridad o condiciones de reintroducción que probablemente guíen un cambio futuro. Clasifica la decisión, no el tamaño de su implementación: un cambio de nombre mecánico aún puede registrar una regla de nomenclatura o compatibilidad duradera.
• Implementada, archivar: una decisión histórica sustancial que está completa y es poco probable que guíe trabajo futuro, pero cuya justificación aún merece conservarse.
• Propuesta, nunca archivar: mantén una propuesta activa; si ya no vale la pena seguirla, recházala con una razón honesta.
• Rechazada, conservar solo como barandilla: conserva un rechazo solo mientras la propuesta perdedora siga siendo un error tentador y significativo y la nota explique por qué pierde; de lo contrario, elimínala.

No archives para cumplir una cuota. Inspecciona cada nota en el ámbito, clasifica grupos análogos bajo un mismo principio y registra las decisiones genuinamente fronterizas para el informe.

Calibración: una nota sobre el estilo de un control de barra lateral colapsada se elimina por larga que sea; una nota que establece que las sesiones son basadas en eventos, o que nombra al propietario único de un directorio de almacenamiento, permanece activa por corta que sea; una nota que registra por qué dos paquetes no deben fusionarse permanece como barandilla mientras fusionarlos siga siendo tentador.

Archivar una nota implementada

1. Mueve la nota completa, con cualquier contraparte traducida, de implemented/<class>/ a archived/<class>/.
2. No hagas ediciones en el cuerpo. Inserta solo Archivado: AAAA-MM-DD inmediatamente debajo de Estado: implementado en cada archivo de idioma, con la misma fecha.
3. Busca enlaces entrantes en la prosa activa. Redirígelos a la autoridad actual, reubícalos en la ruta archivada solo cuando la instantánea histórica se cite intencionalmente, o elimínalos. Nunca verifiques ni repares enlaces desde la nota archivada.

Después del archivo, nunca edites, muevas, traduzcas, reformatees ni elimines la nota. Las notas archivadas siguen siendo destinos de enlace válidos pero no son autoridad para el comportamiento actual.

Validar e informar

Ejecuta commands.docs-check del perfil y git diff --check, y confirma que cada enlace relativo modificado se resuelve. Informa las notas creadas o actualizadas, las notas mantenidas activas, eliminadas, archivadas o rechazadas, y cada caso fronterizo con el resultado elegido.