m1nga/iteration-close

iteration-close — destilar, desechar, probar toma de control, ensayar arranque, sembrar siguiente

Un producto que itera para siempre acumula dos deudas silenciosas, y este skill paga ambas en cada límite de iteración — de forma segura (nada se pierde) pero sin piedad (no se conserva nada muerto):

• Los archivos muertos perduran y se pudren en verdades duales — un árbol obsoleto permanece durante semanas; un manual sigue afirmando que un componente "no está construido" mucho después de que se envió.
• El conocimiento que vive solo en una ventana de chat muere con ella — pipelines de trabajo completos han muerto en borradores; las decisiones ganadas con esfuerzo mueren con la sesión. Conserva la lección, no el artefacto.

Es genérico: funciona en cualquier repositorio leyendo las propias convenciones de ese repositorio, y donde una convención está ausente, crea el mínimo en lugar de asumir o generar un error. "Una ventana nueva o máquina nueva puede continuar" es una ESPERANZA hasta que se PRUEBA; estar al día (pull) siempre es seguro, pero publicar (push) es una elección deliberada. Responde en el idioma en el que el usuario está trabajando.

Dos formas de ejecutar

• Cierre completo (por defecto): las cinco fases, en orden. Úsalo cuando una iteración/trozo está terminado y el usuario quiere cerrarlo de principio a fin.
• Solo desecho (limpieza independiente): cuando el usuario solo pide limpiar archivos viejos/muertos/obsoletos, ejecuta solo la Fase 2 — NO fuerces el cierre completo de cinco actos. Las condiciones previas aún aplican: ejecuta el Paso 0 (orientar), las comprobaciones de rechazo con cierre seguro, y una verificación puntual de la Fase 1 limitada al inventario de eliminación — cualquier elemento cuya lección o decisión viva solo en el chat se destila primero en un archivo rastreado, o se excluye del inventario. Cada regla de la Fase 2 aplica sin cambios, incluida la compuerta de aprobación explícita y la regla de cuarentena.

Paso 0 — orientarse a ESTE repositorio (descubrir, o planificar crear)

Lee el documento de entrada que exista — CLAUDE.md / AGENTS.md / README / un índice docs/ — y descubre seis cosas. Usa lo que encuentres; donde algo esté ausente, anótalo como una brecha que este cierre llenará (cada fase a continuación dice cómo), nunca inventes un camino que no existe.

1. Registro de lecciones/decisiones — ¿dónde guarda este repositorio las decisiones? (CHANGELOG, docs/adr/, DECISIONS.md, o un registro específico del repositorio). Si no hay ninguno, la Fase 1 crea un único DECISIONS.md.
2. Comando de subida confirmado — un paso deliberado de push (bin/sync, make deploy, una disciplina documentada de git push)? Si es así, ESE es el canal de subida; nunca lo eludas. Si no hay ninguno, la Fase 3a usa un git push simple después de un diffstat + confirmación.
3. Comando de arranque — ¿cómo cobra vida un clon fresco? (bin/bootstrap, bin/sync-setup, install.sh, make setup, una instalación de gestor de paquetes). Si no hay ninguno, la Fase 4 crea uno.
4. Comando de prueba — de la configuración de CI, scripts de package.json, un Makefile, o el valor predeterminado del lenguaje (pytest / go test / cargo test / npm test). Si no hay ninguno detectable, el repositorio no tiene aún un conjunto de pruebas ejecutable: trátalo como un estado explícito a continuación — nunca lo interpretes como "verde", nunca RECHAZES un repositorio que legítimamente no tiene ninguno.
5. Skill de compuerta / fundamento — ¿un skill de compuerta de fundamento de producto o pre-construcción? Si es así, su lista de verificación "post-construcción" es tu compuerta de precierre. (Las compuertas específicas del producto viven dentro del repositorio del producto; este skill se mantiene genérico y se aplaza a ellas.)
6. Directorios declarados de datos / recuperación / cuarentena — directorios que el documento de entrada nombra como que contienen datos reales, material de recuperación o archivos en cuarentena. Estos están exentos de cada regla "los directorios con forma de archivo no deben existir" a continuación y nunca deben aparecer en un inventario de eliminación.

Rechazar ejecución (cierre seguro)

No cierres a mitad de iteración — pierdes piel Y carne. RECHAZA (en ambos modos de ejecución) si: el directorio no es un repositorio git (detente y dilo — ejecutar git init es decisión del usuario); el conjunto de pruebas existe y está REALMENTE FALLANDO (un conjunto ausente no es uno fallido — ver Paso 0.4); una compuerta adversaria, si el repositorio tiene una, está pendiente o requiere cambios; u otro agente/vía tiene trabajo no confirmado a mitad de trozo en rutas que tocarías. Di qué está bloqueando y detente.

En un cierre completo, ejecuta las fases EN ORDEN. Cada una tiene una prueba de salida; nunca continúes después de una salida fallida.

Fase 1 — DESTILAR (compuerta de rescate: nada muere antes de que su lección esté bancarizada)

1. Barre las decisiones nacidas en el chat de esta iteración en el registro de decisiones del repositorio (Paso 0.1), cada una con su estado y fuente. Si el repositorio aún no bancariza decisiones en ningún lugar, crear el registro es parte de esta fase — un único DECISIONS.md en la raíz del repositorio es suficiente. Una decisión que existe solo en una ventana de chat no existe; no dejes decisiones destiladas sin un hogar rastreado.
2. Nuevas invariantes/reglas descubiertas en esta iteración → el archivo de contratos del repositorio, o a falta de ese el registro de decisiones — idealmente cada una como una prueba. Si ninguno existe, crea el registro de decisiones y ponlas allí. Elimina el artefacto, conserva la invariante.
3. Verificación de capacidad solo de sesión: ¿dependió esta iteración de algo que vive SOLO en un prompt, un borrador o la memoria de alguien? Promuévelo al repositorio (código / skill / documento) o registra su exclusión deliberada. Nombra cada uno explícitamente — aquí es donde mueren los pipelines.
4. Si la ESTRUCTURA cambió, actualiza — o, si no existe ninguna y la estructura ahora es no trivial, crea — una nota breve de arquitectura/sistema para que siga describiendo la realidad. Pon al día cualquier tablero de estado (por ejemplo, un documento de progreso) si el repositorio tiene uno.

PRUEBA DE SALIDA: busca las decisiones clave e invariantes de esta iteración dentro del repositorio — cada una encontrable en un archivo rastreado. Cualquier cosa encontrable solo en el chat = Fase 1 no terminada.

Fase 2 — DESECHAR (eliminación sin piedad; el historial de git es el ÚNICO archivo)

1. Construye un inventario de eliminación con evidencia, una línea cada uno: ruta | por qué está muerto | qué lo reemplaza. Cubre módulos/especificaciones obsoletos, directorios muertos/vacíos, residuos de desarrollo (archivos de prueba, basura estilo mktemp, filas de prueba en almacenes con forma real), documentos de plan/TODO completados, y DOCUMENTOS OBSOLETOS — realiza un pase de contradicción docs-vs-código; un documento que afirma lo que el código contradice es peor que ninguno. Marca cada línea RASTREADO o NO RASTREADO (git ls-files --error-unmatch <ruta>), porque los dos tienen destinos diferentes (reglas 3 y 4).
2. Presenta el inventario COMPLETO al usuario y espera un sí explícito antes de eliminar nada. La aprobación parcial está bien — actúa solo en las líneas aprobadas. El agente nunca presiona botones irreversibles por su cuenta; "el usuario pidió una limpieza" autoriza construir la lista, no ejecutarla.
3. Archivos rastreados: solo git rm. NO directorios _archive/, NO .bak, NO renombrar como old-/legacy-, NO cadáveres comentados. Recuperación = historial de git, a un git revert de distancia — ese es el archivo; un commit de punto de control antes de eliminar lo hace a prueba de balas.
4. Archivos no rastreados o gitignorados: NUNCA rm directamente — el historial de git no puede recuperar lo que nunca fue confirmado. Esta es la línea de seguridad de datos. En su lugar, muévelos al directorio de cuarentena declarado del repositorio (Paso 0.6). Si no hay ninguno declarado, créalo ahora: .iteration-quarantine/ en la raíz del repositorio, añadido a .gitignore, declarado en el documento de entrada con una línea ("cuarentena para archivos no rastreados pendientes de eliminación — vaciado manualmente por el usuario"). Vaciar la cuarentena es un acto del usuario — ofrécelo en un cierre futuro, con su propio sí explícito; nunca en silencio.
5. Nunca deseches los DATOS reales del producto como si fueran residuos de desarrollo. Estado de usuario/cliente, sesiones guardadas, archivos reales de contenido de usuario parecen desorden y son el alma del producto. Cuando un directorio podría ser cualquiera de los dos, trátalo como datos y consérvalo; verifica antes de cualquier git rm.
6. Confirma las eliminaciones en grupos temáticos; cada mensaje dice POR QUÉ + qué lo reemplaza.
7. Comprobaciones posteriores a la eliminación (todas las que apliquen deben pasar): si el repositorio tiene un conjunto de pruebas, está verde; la búsqueda de referencias colgantes para cada módulo/símbolo eliminado está vacía (una importación de un archivo eliminado falla al inicio — una cicatriz real); el documento de entrada y los documentos del skill no referencian ninguna ruta eliminada.

PRUEBA DE SALIDA: git status limpio, no existen directorios con forma de archivo — excepto los directorios que el documento de entrada declara como datos, recuperación o cuarentena (Paso 0.6) — búsqueda de colgantes vacía, y el conjunto de pruebas está verde si existe uno.

Fase 3 — DOS CANALES DE PREPARACIÓN (necesidades diferentes; verificar por separado)

Subir y poder continuar NO son el mismo problema. Confundirlos es cómo un repositorio se "sube a la nube" mientras su estado real todavía vive en un registro de chat. Verifica cada uno por su cuenta.

3a. Subida confirmada a la nube (el problema de TRANSPORTE)

1. Escaneo de secretos solo en archivos RASTREADOS (sk-ant / ghp_ / gho_ / github_pat / AKIA / xox[baprs] / consumer_secret / access_token / Bearer / BEGIN PRIVATE KEY / formas .env). Cualquier acierto → detente, limpia, vuelve a escanear.
2. Verifica git remote. Si NO hay remoto, la subida necesita uno que el USUARIO proporcione — añadir un remoto es un cambio de configuración, así que confírmalo con el usuario o registra "aún no hay remoto — publicación diferida" y salta a 3b en lugar de fallar con un comando git vacío.
3. Con un remoto: muestra git log @{u}..HEAD --oneline + diffstat (recurre a "todos los commits locales" cuando aún no haya upstream) — exactamente lo que saldrá de esta máquina.
4. Sube a través del comando de subida confirmado del repositorio (Paso 0.2) después de que el usuario confirme; si el repositorio no tiene ninguno, git push después del diffstat y un sí. Nunca auto-pushes.

3b. Toma de control sin contexto (el problema de COMPLETITUD DEL CONOCIMIENTO) — la sonda de arranque en frío

1. Consigue UN lector genuinamente sin contexto en el repositorio — en Claude Code: genera un subagente fresco (herramienta Tarea); en Codex: ejecuta un codex exec fresco o una nueva sesión sin contexto previo; en cualquier harness básico: abre una nueva sesión y pega SOLO la ruta del repositorio más las preguntas, nunca esta conversación. Dale solo la ruta del repositorio y: "Lee este repositorio en frío desde su documento de entrada. Luego responde: (1) ¿qué es este producto, en una oración; (2) ¿dónde está el trabajo (hecho / siguiente); (3) ¿qué harías a continuación y por qué; (4) nombra tres cosas que nunca debes hacer aquí."
2. Califica sus respuestas contra los documentos canónicos del repositorio. Si el repositorio no tiene ningún documento de entrada/canónico en absoluto, crear uno mínimo (el producto en una oración, estado actual hecho/siguiente, tres no-hacer-nunca) es parte de este cierre — es el artefacto que la sonda califica. No ejecutes la sonda contra nada.
3. Cada respuesta incorrecta o faltante es un ERROR EN EL DOCUMENTO DE TOMA DE CONTROL, no culpa de la sonda. Corrige (o crea) el documento, vuelve a ejecutar con un LECTOR FRESCO NUEVO. Repite hasta que un lector en frío puntúe 4/4, con un límite de 3 rondas — si todavía falla después de 3, enumera las brechas restantes y entrega la decisión al usuario.

PRUEBA DE SALIDA: la sonda pasa 4/4. Solo entonces "cualquier ventana nueva / máquina puede continuar" es un hecho probado.

Fase 4 — ARRANQUE EN UN SOLO COMANDO (ensayado, no asumido)

1. Asegúrate de que el arranque del repositorio (Paso 0.3) exista y esté actualizado — idempotente, seguro de volver a ejecutar: verifica las versiones de las herramientas; cablea sincronización/config; instala dependencias; ejecuta el conjunto de pruebas si existe; imprime el estado actual + los NOMBRES de cualquier secreto local faltante (nunca valores, p. ej. "config.local.json ausente — necesario solo para publicación en vivo"); sale con código distinto de cero en cualquier fallo con un motivo de una línea. Si aún no existe ningún arranque, esta es la iteración para crear uno.
2. ENSÁYALO: clona el repositorio en un directorio temporal (desde la URL de origen, o desde la ruta del repositorio local cuando aún no hay remoto) y ejecuta el arranque allí. Debe terminar verde con CERO pasos manuales. Elimina el clon de ensayo después.
3. La historia de la máquina nueva debe ser una línea y VERDADERA después de este ensayo: git clone <url-origen> <dir> && cd <dir> && <comando-de-arranque>. Si aún no existe un remoto, anota que esta línea aún no es verdadera hasta que el usuario configure uno — no la publiques como si funcionara.

PRUEBA DE SALIDA: el clon de ensayo arranca verde, sin intervención humana.

Fase 5 — CERRAR + SEMBRAR (continuidad)

1. Etiqueta la iteración: git tag iter-<N>-<slug> (anotada, resumen de una línea). N = 1 + el recuento de etiquetas iter-* existentes (git tag --list "iter-*"); el primer cierre es iter-1.
2. Actualiza el tablero de estado / registro con una línea, si el repositorio tiene uno: qué se destiló, cuántos archivos se desecharon, sonda 4/4, arranque ensayado.
3. Emite la SEMILLA DE LA SIGUIENTE ITERACIÓN en el chat: las preguntas abiertas que esta iteración sacó a la luz + un prompt de inicio listo para pegar para el siguiente trozo (objetivo, aceptación y un recordatorio de ejecutar la compuerta de fundamento del repositorio antes de construir, si tiene una).

Iteración mayor — cuando la ESTRUCTURA misma es reemplazada (mismas reglas, más piel)

Una revisión estructural — nueva arquitectura, nuevo árbol de módulos, incluso "el enfoque antiguo estaba equivocado" — sigue siendo una ITERACIÓN de un organismo, no un reinicio. Conserva su historial de git, sus decisiones, sus lecciones; solo la piel es nueva. Los reinicios sangran: cada vez que un proyecto renace en un repositorio fresco, el material de nivel de lección se queda atrás. Así que:

• Cultiva la nueva estructura EN ESTE REPOSITORIO junto a la antigua (patrón estrangulador): el nuevo árbol gana pruebas y propiedad primero; el árbol antiguo muere en la Fase 2 solo cuando nada lo referencia.
• Abrir un NUEVO repositorio es la excepción costosa, no el valor predeterminado — requiere una decisión registrada que indique por qué ESTE historial debe ser abandonado, aprobada antes de que cualquier archivo se mueva.
• Mismas cinco fases; el inventario de eliminación solo es más grande y la sonda de arranque en frío importa más — los documentos de la nueva estructura nunca han conocido a un extraño.
• Si el nombre del producto o el comando de entrada cambia, la historia de una línea de la Fase 4 se actualiza en la MISMA iteración. Dos nombres vivos es un error de dos verdades.

Barreras de seguridad (no negociables)

• El orden de las fases es el mecanismo de seguridad: NUNCA deseches (Fase 2) antes de que destilar (Fase 1) salga — en modo solo desecho, la verificación puntual de la Fase 1 en el inventario es esa compuerta.
• El inventario de eliminación completo se muestra al usuario, y NADA se elimina sin su sí explícito. El agente nunca presiona botones irreversibles por su cuenta.
• Los archivos no rastreados o gitignorados se ponen en cuarentena, nunca se rm — el historial de git no puede recuperarlos.
• La eliminación necesita evidencia de reemplazo, no sensaciones. ¿Genuinamente inseguro? CONSÉLVALO UNA iteración más y registra la duda en el registro de decisiones. Escribir una línea es más barato que restaurar desde git.
• Cuando un directorio parece datos de usuario pero también parece desorden, es datos; nunca estarás castigado por preservar en exceso.
• La limpieza de secretos no es un producto de seguridad; es una cortesía. Pero es una cortesía que no debes omitir en los archivos rastreados.
• No inventes la salida de rm -rf; el historial de git no es un arcón de respaldos para lo que nunca se confirmó.

Terminación exitosa (qué resumir)

Al cerrar, el agente debe resumir en el idioma del usuario:

1. ¿Cuántas decisiones bancarizadas? (F1)
2. ¿Cuántos archivos desechados? (F2) — rastreados eliminados / no rastreados en cuarentena / protegidos por falta de confirmación
3. ¿Puntuación de la sonda en frío? (F3b) — rondas tomadas, brechas si las hay
4. ¿Arranque ensayado? (F4)
5. Etiqueta de iteración aplicada (F5)
6. Semilla de inicio para la siguiente iteración (F5)