chrislacey89/compound

¿Qué hace compound?

Documenta un problema resuelto recientemente o una funcionalidad enviada para acumular el conocimiento de tu proyecto. Cada solución documentada hace que la planificación e implementación futuras sean más rápidas — el agente consulta docs/solutions/ durante /research y /write-a-prd, así que las lecciones aprendidas hoy previenen errores mañana.

Cuando el trabajo reveló sorpresas en la planificación o estimación, captúralas también. La calibración al estilo McConnell solo ocurre si el trabajo real retroalimenta la configuración futura.

Posición de Invocación

Esta es una habilidad del pipeline primario que cierra el ciclo de acumulación. Se ejecuta cerca del final de la ruta de entrega por defecto, después de que /pre-merge ha creado la PR.

Por defecto — captura la lección en la PR, antes del merge. Cuando una lección duradera ya se conoce en el momento de la PR, ejecuta /compound en la rama abierta de la PR para que la entrada de docs/solutions/ viaje en la misma PR que el código que la enseñó — revisada antes del mismo merge y fusionada atómicamente con él. Esto coloca /compound entre /pre-merge y /closeout, y regresa a través de /pre-merge una vez:

… → /pre-merge → /compound (en la PR, cuando existe una lección) → /pre-merge (re-ejecutar: el commit de compound es el delta posterior al sello; vuelve a sellar) → /closeout (merge + teardown) → cleanup

El tramo de retorno no es decorativo. Hacer commit en la rama mueve la cabeza más allá del sello que /pre-merge Fase 4 escribió, y /pre-merge es el único escritor del sello — por lo que sin la re-ejecución, la entrada se fusiona con el código y nadie la lee, que es exactamente lo que la opción por defecto en la PR fue diseñada para evitar. La Fase 5 establece la transición; por eso existe.

Alternativa — captura post-merge. Algunas lecciones solo surgen durante o después del merge: sorpresas de integración, hallazgos de QA, comportamiento observado una vez que se envía. Para esos, ejecuta /compound después de que /closeout haya fusionado. Esta es la ruta alternativa, no la predeterminada.

En cualquier caso, /compound nunca realiza el merge o la limpieza del árbol de trabajo por sí mismo — eso es /closeout — y nunca escribe el sello de la moneda de revisión, que es exclusivo de /pre-merge. Capturar en la PR significa hacer commit en la rama abierta de la PR y devolverla para la revisión que la cubre; no significa fusionar.

No lo uses para ediciones triviales o para lecciones que pertenecen enteramente a un artefacto de mayor fidelidad como una prueba, regla de linter o comentario de código sin ningún aprendizaje duradero a nivel de proyecto. Ya sea en la PR o post-merge, la salvaguarda "Cuándo NO Usar" a continuación sigue aplicando — la mayoría de las PR no contienen una lección duradera, y no hay un espacio permanente por PR en docs/solutions/ que llenar.

Por Qué Existe

Sin este paso, has hecho ingeniería tradicional con asistencia de IA. Los primeros tres pasos del flujo de trabajo (planificar, trabajar, revisar) producen una funcionalidad. Este cuarto paso produce un sistema que construye funcionalidades mejor cada vez.

Cuándo Usar

• Cuando la PR de una funcionalidad está lista y enseñó una lección duradera — captúrala en la PR antes del merge (la ruta feliz)
• Después de enviar, cuando una lección solo se aclaró durante o después del merge (la ruta alternativa post-merge)
• Después de corregir un bug complicado donde la causa raíz no era obvia
• Después de que un ciclo de QA reveló problemas que podrían haberse detectado antes
• Después de tomar una decisión arquitectónica con compensaciones significativas
• Cuando has descubierto un patrón que debería reutilizarse

Cuándo NO Usar

• Para correcciones triviales (correcciones tipográficas, cambios simples de configuración)
• Cuando la solución ya está bien documentada en la documentación oficial de la biblioteca
• Cuando la lección es específica del proyecto pero estás a punto de desaprobar ese código
• Cuando el trabajo fue una ejecución limpia de un plan predefinido — sin sorpresas, sin retrabajo, sin decisiones no obvias. El cuerpo del issue y la descripción de la PR ya contienen ese registro; una entrada de docs/solutions/ sin una lección reutilizable entrena a los lectores futuros a hojear
• Cuando tengas dudas — saltarlo no cuesta nada porque el issue y la PR persisten en GitHub. Capturar una lección de bajo valor cuesta la atención de los planificadores futuros cada vez que consultan docs/solutions/

Flujo de Ejecución

Fase 1: Identificar Qué Capturar

En la ruta por defecto en la PR, el trabajo bajo revisión es la rama abierta de la PR, por lo que los comandos a continuación la leen directamente — un git log y un git diff de la rama contra la base en la que se fusionará, mientras aún no está fusionada. En la ruta alternativa post-merge, ejecútalos en una sesión que aún pueda ver el historial de la funcionalidad fusionada — una vez que /closeout ha podado la rama y actualizado la base, ese diff está vacío y debes leer el diff de la PR mediante gh pr diff <n> en su lugar. De cualquier manera, revisa el trabajo reciente.

Resuelve la base primero. No codifiques main — este repositorio mismo usa prod, y un nombre no es una referencia: en un flujo de trabajo de worktree nadie verifica la rama base, por lo que la rama local está congelada en el momento en que se hizo el checkout mientras origin/<base> avanza. Pregunta a sidecar.sh base-ref; no derives la base.

SC="<directorio de esta habilidad>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref falló: no adivino una base" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

Mira:

1. Git log — ¿Qué commits se hicieron? ¿Qué cambió? Relativo a la base, no -20: un conteo fijo lee la historia de la base como "el trabajo bajo revisión" en cualquier rama más corta que él. Dos puntos aquí es correcto — estos son los commits en esta rama y no en la base. (El git diff es de tres puntos por la razón espejo: diferencia desde la base de fusión en lugar de restar el trabajo del lado de la base.) En la ruta alternativa post-merge la rama ha desaparecido, así que usa gh pr diff <n> como se indicó.

2. Hilo del issue — ¿Cuál era el problema original? ¿Qué se discutió?

3. El diff — ¿Qué archivos cambiaron? ¿Qué patrones surgieron?

Pregunta al usuario: "¿Cuál fue lo más importante que aprendiste o la parte más complicada de esta funcionalidad?" Su respuesta a menudo revela la lección de mayor valor para capturar.

Antes de escribir, clasifica la lección en el nivel correcto:

• Evento — un incidente aislado o fallo visible
• Patrón — algo que ha ocurrido repetidamente a través de funcionalidades, bugs o traspasos
• Estructura — una condición recurrente en el código base, flujo de trabajo, incentivos o proceso de decisión que sigue produciendo el patrón

Prefiere capturar el nivel más alto que puedas respaldar con evidencia. Si la lección es estructural, nombra el bucle de retroalimentación, la retroalimentación faltante o el efecto retardado que hizo probable el resultado.

Antes de proceder, responde cuatro preguntas:

1. ¿Es genuinamente nuevo? Revisa la documentación oficial de la biblioteca y los almacenes que cubre la búsqueda de superposición de la Fase 4. Si la lección ya está bien documentada en otro lugar, sáltala o enlaza a la fuente existente.
2. ¿Seguirá siendo preciso en 3 meses? Si la lección está estrechamente acoplada a una versión de dependencia o a una solución temporal, anótalo — afecta la clasificación de volatilidad a continuación.
3. ¿Podría capturarse más cerca de la fuente? Un invariante de comportamiento es mejor como prueba. Una convención es mejor como regla de linter. Una explicación de "por qué" es mejor como comentario de código colocalizado con la decisión — limitado al por qué actual, la razón que un lector necesita para entender el código tal como está ahora. El incidente que lo descubrió pertenece al mensaje de commit y al cuerpo de la PR, donde un lector que reconstruye la historia ya busca; el Paso 3 de /execute establece esa ruta en el momento en que se escribe el comentario, y esta pregunta es la verificación retrospectiva. Si la lección puede capturarse en un artefacto de mayor fidelidad, hazlo en lugar de escribir prosa. Esto se trata de llevar la lección — la verificación de agrupamiento de la Fase 4 pregunta algo diferente: si un mecanismo debería detectar la próxima instancia, y una recurrencia puede requerir uno aunque la lección en sí necesitara prosa.
4. ¿Se corrigió el proceso? (Solo para compuestos de corrección de bugs.) ¿La corrección fue una corrección (eliminó el defecto) o una solución temporal (suprimió el fallo)? ¿Se encontraron y abordaron patrones estructuralmente similares en otros lugares del código base? ¿Qué cambio de proceso evitaría que esta clase de defecto volviera a entrar al código base — una prueba más fuerte, una regla de linter, una aserción, un elemento de lista de verificación de planificación o un issue presentado en chrislacey89/skills (ver Presentar contra el pack a continuación)? Si la respuesta es "nada", el mecanismo que produjo este defecto sigue activo.

Presentar contra el pack — el quinto mecanismo

Esta subsección no está restringida a correcciones de bugs. La P4 anterior lo dice (su encabezado lo indica), pero tanto la P4 como la regla de promoción a mecanismo de la Fase 4 citan las reglas a continuación, y la Fase 4 no está restringida a correcciones de bugs. El incidente para el que existe este mecanismo fue un compuesto de funcionalidad. Un procedimiento alcanzable solo desde la ruta que su propio incidente no tomó es el defecto que se corrige, un nivel más abajo — por lo que las reglas se declaran aquí, una vez, y ambas fases apuntan a ellas.

El quinto nombre está limitado por la propiedad, no por la dificultad. Los primeros cuatro son artefactos de este código base; el quinto existe porque algunos cambios preventivos no lo son — son cambios en la prosa, compuerta, traspaso o prueba de contrato de una habilidad en chrislacey89/skills, que ningún artefacto descendiente puede llevar en absoluto. Eso, y solo eso, es cuando el quinto nombre califica. No califica porque los primeros cuatro son difíciles, costosos o poco claros aquí: esa es la salida de cumplimiento que chrislacey89/skills#257 dejó deliberadamente cerrada, y "no pude construir uno" aún se resuelve como siempre lo hizo — nombrando en la entrada cuál de los cuatro se acercó más y qué lo bloqueó.

Compuerta del propietario de presentación (DO-CONFIRMAR — verifica antes de escribir cualquier salida)

Presentar mueve palabras fuera del repositorio en el que te encuentras, a uno público. Eso es un acto diferente de todos los demás mecanismos en la lista — una prueba, una regla de linter, una aserción y un elemento de lista de verificación se quedan donde están. Así que antes de redactar un cuerpo, confirma que el propietario del repositorio actual es uno al que tienes permiso para presentar desde:

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

Compáralo con la lista de permitidos a continuación. La lista de permitidos es toda la compuerta — un propietario que no esté en ella no está permitido, incluyendo un propietario que no reconozcas. No inviertas esto en "bloquear los propietarios que sé que son trabajo": una organización cliente que fue incorporada la semana pasada no está en la lista de nadie todavía, por lo que una lista de denegados admite exactamente el repositorio con la postura de confidencialidad menos conocida. Falla cerrado en desconocido.

chrislacey89

Los marcadores alrededor de esa valla son críticos: esta subsección contiene varios bloques de código, por lo que "la lista es el bloque de código a continuación" es ambiguo para cualquier cosa que lo lea mecánicamente — un lector que adivina incorrectamente extrae prosa y cada propietario falla entonces la verificación. Coincide con los marcadores, no con la posición.

Agrega un propietario a esa lista solo como una edición deliberada y revisada — una línea, fuera de línea, buscable. Un repositorio público al que contribuyas califica una vez que lo nombres; no califica meramente por ser público. La visibilidad es una propiedad remota mutable, una bifurcación pública puede ocultar un padre privado, y — la razón por la que esto importa aquí — lo que se presenta es una narrativa sobre el trabajo, no el código del repositorio. Código fuente público y un compromiso confidencial en torno a él es una combinación ordinaria, y "nos encontramos con esto mientras construíamos X para Y" filtra la relación incluso cuando cada línea es legible para todos.

Cuando el propietario no está en la lista de permitidos, el quinto nombre no está disponible. Vuelve al comportamiento anterior a este mecanismo: registra la prescripción en el espacio de Prevención → Nivel de proceso de la entrada, recomienda /improve-pipeline, y deja que un humano lo lleve. La lección no se pierde; simplemente no viaja automáticamente.

Redacción y presentación

Cuando tanto la guardia de propiedad como la compuerta del propietario de presentación pasan, presentar es el mecanismo, y /compound lo presenta — la prescripción que llega a este repositorio es el artefacto, no una oración que recomienda que alguien lo lleve allí. Primero verifica superposición y comenta en el issue existente en lugar de presentar uno nuevo; un nuevo canal saliente hacia un backlog solo vale la pena si no se llena de repeticiones.

gh issue list -R chrislacey89/skills --state all --search "<área del pipeline> <palabras clave del modo de fallo>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <área del pipeline> — <prescripción>" --body-file <archivo>

--title y --body* son obligatorios, no estilísticos: gh issue create sin ninguno falla bajo cualquier ejecutor no interactivo, que es cada ruta AFK que este mecanismo debe sobrevivir.

Escribe el cuerpo anonimizado y trata eso como parte del contrato, no como buenos modales. La compuerta anterior decide si puedes presentar; esto decide qué cruza. Describe la forma del incidente, no su sujeto:

• Nombra el archivo del pack que el cambio afecta, el paso del pipeline que lo omitió, y qué debería haber hecho en su lugar.
• No nombres el repositorio descendiente, su propietario, su cliente, sus rutas, sus identificadores, ni sus números de issue y PR. Caracterízalo — "un repositorio descendiente de TypeScript web/page-analysis" — como lo hizo chrislacey89/skills#266, que es el ejemplo trabajado: abre Triggering repo: anonymized y registra que la fuente fue deliberadamente despojada de identificadores.
• No cites la ruta de esta entrada como evidencia. Una ruta docs/solutions/… es un nombre de archivo de un repositorio al que el lector puede no tener acceso, por lo que no prueba nada para ellos e identifica el trabajo para todos los demás. Lleva el razonamiento; la entrada se queda en casa.

El archivo del pack y la forma del fallo son lo que hace que una propuesta sea accionable aquí. Todo lo que la regla de anonimización elimina es detalle que solo era legible en el repositorio del que vino.

Mantenlo corto. Esto es un esbozo de propuesta, no una propuesta trabajada — /improve-pipeline es lo que desarrolla una, y la recomendación de /improve-pipeline más adelante en esta fase sigue siendo válida: recomiéndalo, no lo invoques. Cita el número de issue en la entrada. Una presentación no citada es prosa otra vez: la entrada nombra #N, o el quinto nombre no se usó.

Revisión de Rabbit Hole.

...

[truncado para traducción]