Mantenimiento de Documentación

Documentación de Mantenimiento

1. Aclarar responsabilidades y el alcance actual

Use este skill para decidir si crear o reutilizar registros, organizar contenido, verificar descripciones, exponer brechas y mantener relaciones de origen, estado y navegación. Esto requiere criterio de ingeniería: investigue las rutas reales al explicar los mecanismos actuales; no se limite a reformatear la conversación ni cree certeza falsa completando plantillas.

• El Agente que maneja la tarea actual se encarga de las decisiones técnicas, compensaciones, desglose de tareas, implementación, depuración y verificación; use estas reglas compartidas cuando los resultados deban conservarse. La investigación específica y las actualizaciones de la documentación del subsistema son tareas válidas y no requieren iniciar un proceso de diseño separado primero.
• Use to-docs para crear entregables de diseño legibles para humanos que las personas puedan revisar, editar y consultar más tarde. Un diseño legible para humanos puede ser la fuente completa; este skill guía la propiedad y consistencia de los documentos desde el momento en que se guardan. No requiera un registro de ingeniería primero ni cree llamadas circulares entre skills.
• Use grilling para aclarar el tema actual en profundidad; grill-me es su punto de entrada explícito. Continúe desde el contenido establecido sin reabrir decisiones ni agregar puertas de aprobación para cada iteración.
• Use decision-notes para encontrar, registrar, reemplazar y organizar decisiones a largo plazo. Este skill hace referencia a sus conclusiones; no establece un proceso de entrevista separado ni un ciclo de vida de decisiones. Busque cuando se apliquen sus condiciones de activación, incluso si no hay un enlace directo.
• Use handoff según sea necesario para preparar o verificar una transferencia entre sesiones o Agentes. Este skill continúa manteniendo los materiales de ingeniería y el estado; no cree un duplicado completo solo porque la persona que ejecuta la tarea cambió, y no cree llamadas circulares entre skills.
• La lectura ordinaria, las preguntas inmediatas y los cambios pequeños que no afectan los materiales existentes no activan de forma independiente el proceso completo de mantenimiento; aún así, lea los materiales necesarios para la tarea. Una solicitud solo de documentación no amplía la autorización para cambiar el comportamiento del producto, ejecutar verificaciones no relacionadas ni commitear código; la autorización existente de la tarea de ingeniería permanece vigente.

Use los nombres realmente disponibles en el entorno. Si no se puede invocar un skill, lea la configuración guiada del proyecto en su lugar; no afirme haber invocado un skill no disponible. La colaboración no debe causar carga circular ni búsquedas duplicadas.

2. Localizar fuentes y decidir si reutilizar o crear registros

Comience desde el punto de entrada real del Agente del proyecto para localizar restricciones, requisitos y criterios de aceptación, subsistemas relevantes, registros de cambios y notas; verifique el alcance del trabajo actual. Para proyectos existentes, prefiera ubicaciones y nombres existentes; no exija migración. Para trabajo entre subsistemas, cubra las interfaces relevantes y las restricciones compartidas.

Reutilice el contexto ya leído y verificado para la misma tarea si aún aplica. Cuando el alcance, una premisa clave o una fuente cambien, o aparezca un conflicto, vuelva a verificar las áreas afectadas. No vuelva a escanear todo el repositorio ni reinicie una entrevista simplemente porque cambió el turno o el skill.

Al elegir ubicaciones, nombres, divisiones de archivos o navegación, lea Organización y Fuentes.

1. Primero busque documentación existente que aún aplique al mismo cambio; un tema similar no significa necesariamente el mismo cambio. Para continuar trabajo existente, localice su registro original y verifique el estado actual en lugar de escribir automáticamente un documento de transferencia completo.
2. Cree o actualice registros cuando los diseños objetivo, los planes de migración, las dependencias o las preguntas a investigar o verificar deban conservarse para implementación, aceptación o continuación entre sesiones posteriores. Esto también aplica durante la investigación y la comparación de soluciones.
3. Los cambios pequeños y claros completados en el turno actual pueden entregarse solo en la conversación, mientras se mantiene la documentación existente afectada y las notas requeridas por reglas establecidas. Si el usuario solicita explícitamente guardar algo, regístrelo, prefiriendo una fuente existente apropiada.
4. No cree registros mecánicamente basándose en la cantidad de líneas, archivos, turnos de conversación o commits. No cree previamente páginas vacías ni una biblioteca de documentación completa, y no pregunte cada vez si debe escribir documentación.

3. Verificar y mantener los materiales según su propósito

Trabajo actual	Leer según sea necesario	Propiedad de la información
Verificar la propiedad y alineación entre diseños legibles para humanos y materiales de ingeniería	Organización y Fuentes	Los diseños legibles para humanos conservan la fuente completa de objetivos, escenarios y comportamiento; los materiales de ingeniería los referencian y complementan
Describir un subsistema actual o corregir diferencias entre documentación e implementación	Documentación del Subsistema	Responsabilidades actuales, mecanismos, contratos y navegación al código fuente, pruebas y notas
Registrar objetivos de cambio, diseños, tareas y contexto de continuación	Diseños y Planes de Cambio	Objetivos actuales, brechas con el estado existente, preguntas sin resolver, planes de implementación y verificación
Actualizar estado; completar, pausar, cancelar, reanudar o cerrar registros	Estado y Cierre	Progreso general, resultados de tareas, verificación real y disposición del trabajo restante

Mantenga cada hecho en un solo lugar; resúmalo y enlácelo en otros lugares. docs/designs/<topic>.md puede ser la fuente de diseño legible para humanos completa. Agregue detalles de ingeniería, dependencias, verificación y progreso a .agents/changes/ solo cuando sea necesario; no duplique el diseño. No convierta una visión general de una fuente existente en una copia completa, cree un segundo registro de estado o progreso en un índice, ni mantenga la justificación a largo plazo fuera de su fuente de notas.

El punto de entrada del cambio de ingeniería, el README, el plan y las reglas de Estado general aplican solo al trabajo que necesita un registro de cambio de ingeniería; no se imponen a los diseños legibles para humanos. El contenido resuelto o no resuelto de un diseño no es progreso de ingeniería. No introduzca una máquina de estado de diseño obligatoria ni cree un directorio de ingeniería complementario para cada diseño.

Distinga las conclusiones resueltas, las recomendaciones no resueltas, las suposiciones y los elementos a investigar de la verificación del código fuente, la cobertura de pruebas existente y la verificación real en tiempo de ejecución. Los enlaces deben explicar el mecanismo, el comportamiento cubierto o el tema de decisión que respaldan. La existencia de una prueba no significa que se haya ejecutado correctamente. Adoptar un objetivo no significa que se haya implementado ni elimina automáticamente las obligaciones de transición o compatibilidad.

Cuando la documentación y la implementación discrepen, verifique el código fuente relevante, las pruebas, los requisitos, las notas aplicables y el estado de implementación. Determine si la documentación está desactualizada, la implementación se desvía del comportamiento previsto o una transición está incompleta. Corrija los errores de documentación verificados; aborde los errores de implementación dentro de la autorización existente. No describa un defecto como un contrato normal ni use documentación antigua para anular una nueva instrucción del usuario. Si el comportamiento clave o las compensaciones siguen sin estar claros, describa el conflicto y pida al usuario que decida mientras continúa el trabajo que no depende de esa decisión.

4. Mantener los materiales sincronizados con los cambios sustanciales

• Cuando cambien las responsabilidades del subsistema, los límites, las rutas principales, las interfaces, el estado, el comportamiento de fallo, el comportamiento de compatibilidad o la navegación necesaria, actualice la documentación relevante junto con el cambio verificado, en lugar de esperar a que finalice el proyecto. No reescriba mecánicamente descripciones que sigan siendo precisas después de una refactorización interna, pero repare los enlaces rotos.
• Actualice los diseños cuando los objetivos, el alcance, las opciones clave o las premisas cambien claramente; continúe etiquetando el contenido no resuelto como no resuelto. Actualice los planes cuando los resultados de las tareas, las dependencias, los bloqueos o los próximos pasos cambien de manera que afecten la ejecución o la continuación. Sincronice los cambios importantes en el cronograma antes de ejecutar los pasos afectados; no registre cada operación de herramienta.
• Maneje los ajustes dentro de la autorización existente de forma autónoma. Las actualizaciones de documentación no agregan requisitos de aprobación y no pueden reemplazar una decisión necesaria del usuario. Pida al usuario que decida sobre cambios de comportamiento, alcance o compensaciones clave que excedan la autorización; no reconfirme asuntos resueltos.
• Antes de la entrega, pausa o transferencia, verifique que los materiales relevantes que requieren retención continua permitan que el siguiente Agente identifique el estado actual, la brecha con el objetivo, el trabajo restante y el siguiente paso. No espere hasta estos momentos para hacer el primer registro.

Maneje solo el alcance relevante para la tarea actual. Mantenga los hechos actuales en la documentación del subsistema, las decisiones a largo plazo en decision-notes, y haga que otras ubicaciones los referencien.

5. Verificar y entregar

Verifique el alcance acordado para esta tarea; no la convierta en una auditoría de todo el repositorio:

1. Cobertura y propiedad: Retenga el contenido que necesita persistir; reutilice fuentes apropiadas sin prosa duplicada, marcadores de posición vacíos ni contexto de continuación dejado solo en la conversación temporal.
2. Precisión: Haga que el estado actual, los objetivos, los puntos resueltos y no resueltos, y la evidencia sean claros; no confunda el progreso de la etapa, los cambios de código, la verificación exitosa y la aceptación manual requerida.
3. Estado y continuación: Si existe un registro de cambio de ingeniería, mantenga su Estado general solo en el punto de entrada del cambio y marque las tareas según el progreso real. Haga que los bloqueadores relacionados, las brechas, los próximos pasos y el trabajo restante sean localizables; retenga las conclusiones y la evidencia necesarias en los registros de cierre.
4. Enlaces y consistencia: Mantenga los requisitos y criterios de aceptación, diseños, planes, subsistemas y notas relevantes conectados con precisión; asegúrese de que los enlaces funcionen. La reorganización de materiales o registros no debe perder información única.
5. Alcance de verificación: Ejecute las comprobaciones existentes aplicables según la tarea y el proyecto, y revise los resultados; realice una revisión manual si no existe una herramienta dedicada. No imponga comprobaciones no relacionadas, un conjunto de pruebas completo ni una nueva cadena de herramientas solo para completar la documentación. Reutilice los resultados verificados cuando el contenido no haya cambiado y describa con precisión las áreas no verificadas o restringidas.

Completar la tarea de documentación actual significa que la información acordada es precisa, las fuentes son localizables, las incógnitas y las brechas de verificación se revelan, y los materiales respaldan la continuación. No prueba que el diseño sea suficiente, que la implementación sea correcta o que la funcionalidad esté completa. Verifique la finalización del cambio general por separado usando Estado y Cierre.

Entregue los cambios, las comprobaciones y las brechas necesarias de esta ronda con una explicación concisa y enlaces a los archivos reales; coloque los resultados que necesitan mantenimiento continuo en el repositorio. Mantenga el código relacionado, la documentación y las notas juntos como un entregable pendiente. Guardar documentación no autoriza commit, push, PR ni release; siga las reglas de confirmación existentes del proyecto y no haga commit temprano solo porque se guardó la documentación.