Xs-trek/frame-align

frame-align: alinear el marco primero, luego implementar

¿Qué problema resuelve este skill?

El usuario llega con una idea de software. Puede ser una frase, un esqueleto con contenido faltante, un borrador con errores, un problema estancado o cualquier otra forma. Si en ese momento se comienza directamente a implementar, lo más probable es que se genere algo que ambas partes creen entender, pero que en realidad no está alineado.

Este skill te permite alinear el marco contigo y el usuario antes de comenzar: colocas tu comprensión y propuestas en una página, el usuario responde con clics y notas, y así sucesivamente hasta que el usuario considere que el marco es válido, para luego pasar al llenado de contenido.

La métrica de éxito es si el usuario logra alinear el marco con menos esfuerzo. Si al cargar este skill, el usuario tiene que leer más, completar más o esperar más, es un fracaso, incluso si el proceso se sigue perfectamente.

Hay que evitar dos tipos de fracaso simultáneamente:

• Demasiado pesado: el proceso y el formato te encasillan, ideas diferentes reciben preguntas idénticas, y tu propia percepción y creatividad no emergen.
• Demasiado ligero: saltas la alineación y das soluciones directamente, o la página es solo una versión disfrazada de una respuesta normal, sin diferencia con no usar el skill.

La manera de encontrar el equilibrio es: la forma del ciclo es fija, pero el contenido del ciclo es tuyo. Al empezar, todo debe ser ligero; solo cuando los medios ligeros no sean suficientes, se añade peso.

¿Empezar, continuar o rehacer?

Revisa si existe .frame-align/state.js en el directorio de trabajo actual.

• No existe: empezar.
• Existe y phase es framing: no se completó la vez anterior. Lee el estado, informa al usuario en qué ronda se detuvo y qué se estaba haciendo, y continúa desde allí.
• Existe y phase es filling: rehacer, ver la sección "Rehacer".
• El usuario dice que es otra idea: pregúntale primero qué hacer con la anterior; por defecto, renombra el directorio anterior para conservarlo y luego empezar.

Empezar

1. Leer primero, luego preguntar. Lee todo lo que puedas sobre los archivos mencionados por el usuario, el repositorio de código, los documentos existentes. Si ya hay código, presenta lo que leíste como tu comprensión para que él confirme, sin preguntar nuevamente.
2. Reformular con tus propias palabras. Escribe tu comprensión de su necesidad en un párrafo, sin copiar sus palabras exactas. Copiar no demuestra comprensión; cambiar la forma de decirlo revela desviaciones.
3. Seleccionar preset. Si él especificó un nombre al invocar, úsalo; si no, elígelo tú y explica en una frase en la página de inicio "qué se está haciendo en esta ronda", que él puede cambiar. Ver "Acciones y presets".
4. Generar página de inicio. La página de inicio solo contiene: sus palabras originales, colocadas tal cual arriba, como ancla objetivo (solo él puede modificarlas después); tu comprensión; el contenido de la primera ronda según el preset; un cuadro de texto donde se pueda escribir cualquier cosa; y un botón de envío. Junto al cuadro de texto, añade: "Si te es cómodo, cuéntame tu experiencia técnica; si no, también está bien". Puedes incluir algunas opciones de experiencias relevantes al proyecto para que las seleccione. Pregunta por experiencia, no por pruebas.

La página de inicio es la primera impresión del usuario sobre este skill y también el momento en que menos lo conoces, por lo que debe ser la página más ligera de todas.

¿Cómo avanza una ronda?

1. Verificar. Revisa si los archivos que usaste como base han cambiado, ya que el usuario podría haber modificado algo durante la interacción. Si cambiaron, vuelve a leerlos y marca los nodos dependientes como "base modificada".
2. Explorar. Lee código, consulta información, reflexiona; cómo lo hagas depende de ti. Hay dos límites. Antes de la salida, no escribas código de producto, no configures andamios, no instales dependencias. Si necesitas ejecutar código del proyecto, llamar a servicios externos o escribir archivos fuera de .frame-align/, pregunta primero; si quieres hacer un experimento pequeño y único, hazlo en un directorio temporal fuera del proyecto, pero también pregunta primero.
3. Escribir estado. Guarda el estado actual del marco y las propuestas de esta ronda en .frame-align/state.js, siguiendo el formato en references/state-format.md.
4. Presentar. La página es predefinida; tú no escribes HTML, solo escribes el estado. En la primera ronda, inicia el servicio de página en segundo plano y entrega al usuario la dirección que imprime; en rondas posteriores, solo escribe el estado y, cuando el usuario envíe, la página se actualizará sola a la nueva ronda. La forma de iniciar y la alternativa sin tiempo de ejecución se encuentran en references/page-contract.md.
5. Esperar respuesta. El usuario hace clic, escribe notas y envía en la página. La página guarda el resultado como .frame-align/returns/round-N.txt. Cuando el usuario regrese al diálogo y lo mencione, ve a leer ese archivo.
6. Ajustar. Lee el archivo de respuesta, actualiza el marco, el registro y las observaciones, y luego vuelve al paso 1, o pasa a la salida.

Cada página debe incluir una o dos frases sobre qué se está haciendo en esta ronda: qué leíste de su retroalimentación anterior, qué cambiaste por ello, y qué planeas hacer en esta ronda. Así el usuario sabe que su retroalimentación fue escuchada. Una reformulación completa solo se da en tres momentos: al inicio, cuando la dirección cambia, y antes de la salida; cada vez, con un límite de un párrafo.

El diálogo fuera de la página también debe ser ligero:

• Al entregar la página, solo di dónde está la página y qué se hizo en esta ronda, una o dos frases. No repitas el contenido de la página. Luego espera, sin anticipar su respuesta.
• Los clics en la página no equivalen completamente a su intención. Las palabras escritas por él en el diálogo representan mejor lo que quiere; si hay discrepancia, prioriza lo escrito por él y agrégalo al archivo de respuesta de esa ronda.
• No le pidas que copie los resultados de la página al diálogo. Las respuestas van por archivo; el diálogo queda para sus propias palabras.
• Responde directamente las preguntas que se puedan responder en una frase y guarda el resultado en el estado, sin necesidad de abrir una nueva ronda.

Acciones y presets

Cada ronda selecciona una combinación de estas acciones. El usuario puede pedir cambiar.

Acción	Qué hacer
Reformular	Escribe tu comprensión con tus propias palabras y pídele que la verifique
Divergir	Ofrece inspiración y direcciones
Completar	Señala vacíos en el marco. Para proyectos de software, consulta references/lenses.md
Cuestionar	Señala contradicciones, riesgos, errores
Converger	Ayúdale a priorizar y ordenar entre múltiples direcciones
Explicar	Responde a las dudas que haya marcado

En la fase de divergencia, evita cuestionar: el marco aún no está establecido y criticar temprano solo apaga las ideas.

Presets: intervención inicial, que se reduce con la retroalimentación

Al inicio, no sabes casi nada del usuario. Los presets te ayudan a establecer la dirección: qué hacer en la primera ronda, qué no hacer, y cómo avanzar normalmente. Influyen más en la primera ronda. En rondas posteriores, si la retroalimentación del usuario dice algo, sigue esa; si no dice nada, recurre al preset. Cuanta más retroalimentación, menos influye el preset; cuando ya no tenga nada que aportar, no lo menciones más.

Cuando te alejes del camino del preset, explica por qué en "Qué se está haciendo en esta ronda". Si el usuario dice que ninguno le parece adecuado, tú mismo crea una combinación.

Preset	Lo que trae el usuario	Primera ronda	Cómo avanzar normalmente
Semilla	Una frase, o una idea difusa	Reformular, dar algunas direcciones. No cuestionar, no indagar en detalles	Divergir hasta que diga basta, luego completar, luego converger
Esqueleto	Marco general presente, muchos lugares vacíos	Reformular y dibujar el esqueleto, marcar vacíos, preguntar desde el que más impacte globalmente	Completar uno por uno, verificar si encajan, luego converger
Revisión	Borrador relativamente completo, quiere saber qué falla	Reformular, confirmar que se entendió; señalar una o dos contradicciones o riesgos más importantes	Alternar cuestionamiento y corrección, cubrir omisiones, luego converger
Dificultad	Un problema estancado, o un punto donde no sabe si se puede hacer	Reformular el problema, exponer tu punto clave y fundamentos, dar la verificación que mejor distinga las posibilidades. No expandir una matriz de pruebas	Localizar el punto clave, hacer la verificación mínima, definir plan con los resultados, luego completar y converger

Dificultad: primero localizar, luego probar

Cuando el usuario trae un problema difícil, la forma más ineficiente es probar todas las soluciones posibles una por una. Primero identifica el punto clave: qué factor determina más el éxito o fracaso, qué verificación puede eliminar más posibilidades de una vez. Preséntale tu localización y fundamentos, luego discute cómo resolver.

La verificación está sujeta a los límites del paso de exploración en "Cómo avanza una ronda". Presenta la verificación como algo que necesita su decisión, indicando qué se ejecutará y qué se afectará; si él lo acepta, es un acuerdo. Solo haz una verificación que pueda cambiar el juicio del siguiente paso; cuando salgan los resultados, decide el siguiente.

Su comprensión del problema varía. El enfoque es igual que en otros casos: observa su reacción real, no lo categorices. Si ya tiene claro el punto clave, parte de su juicio para verificar, sin empezar desde cero. Si solo ve el fenómeno, ayúdalo a convertir el fenómeno en un problema, explicando en términos que pueda juzgar cuál es el punto clave y por qué.

La divergencia puede continuar indefinidamente

Algunos usuarios solo quieren que sigas dando ideas. En cada ronda, ofrece nuevas direcciones; él puede guardar, descartar o pedir más, y tú ajustas la siguiente ronda en consecuencia. No decidas por tu cuenta que ya hay suficientes ideas; solo cuando él indique que es suficiente, pasa a completar y converger.

Si hay una dirección digna de mención que se sale de su línea de pensamiento actual, menciónala y explica en qué se sale. Si no, no la fuerces.

Lo fijo y lo flexible

Fijo (sin esto, sería igual que un diálogo normal):

• Tu comprensión, las propuestas de la ronda y el estado actual del marco se escriben en el archivo de estado y se presentan en la página.
• Cada ronda, dile qué leíste de su retroalimentación anterior y qué cambiaste por ello.
• Cada una de sus respuestas se guarda tal cual en returns/.
• El ancla objetivo solo puede modificarla él. Si tus propuestas se desvían de ella, dilo explícitamente.
• Si se modifica un nodo ya confirmado, explica el motivo en el registro.
• La decisión de pasar a la siguiente fase es suya. Puedes sugerir "creo que podemos cerrar, quedan estos dos puntos", pero no puedes declararlo por él.

Estas son reglas baratas; solo hay que seguirlas y no consumen su atención.

Flexible (controlar esto mataría tu criterio):

• Qué proponer, qué preguntar, cuánto preguntar.
• Qué forma usar: texto, diagrama, tabla, comparación, esquema.
• Qué acciones usar en esta ronda y en qué proporción.
• Cuándo sugerir converger.

No dejes que el usuario abandone el poder de decisión

Que el usuario esté de acuerdo contigo no es el problema. El problema es que deje de tomar decisiones. Situaciones comunes:

• La salida es demasiado larga y no la lee; solo espera el resultado final para juzgar si es correcto. Las desviaciones se descubren al final, tiempo perdido.
• Confía en ti y, ante contenido que parece profesional y creíble, solo dice "continúa"; tú te desvías cada vez más o te equivocas, y nadie lo nota.
• Otras situaciones donde, sin darse cuenta, delega las decisiones, como: tener que decidir demasiadas cosas a la vez; opciones escritas en términos que no entiende; tú decides por él sin que lo sepa.

La causa suele estar en tu salida, así que primero controla tu salida:

• Menos es más. Cada ronda, pon solo lo más importante frente a él; el resto, recógelo y muéstralo solo si él quiere verlo.
• Separa lo que necesita su decisión. Ponlo aparte de lo que ya has decidido por él; lo que realmente necesita decidir, al principio.
• Habla en términos que pueda juzgar. No uses extensión ni jerga para parecer creíble. En áreas que no conoce, traduce las opciones en consecuencias, por ejemplo, "elegir esto significa que cambiar de plataforma más adelante requerirá reescribir". Las partes que no puede juzgar, verifícalas tú mismo, no le preguntes.
• Puedes decidir cosas pequeñas por él. Siempre que la respuesta no cambie la dirección del marco, sea fácil de cambiar después y él no haya mostrado preocupación. Cuando decidas, enuméralo en una lista corta en la página de esa ronda; cada elemento puede ser revertido por él. Si él dice "tú decides", hazlo igual y enuméralo. Las decisiones importantes no entran aquí: aquellas que, si se equivocan, requieren rehacer otras partes del marco; incluso si dice "tú decides todo", pon las más importantes frente a él.

No hay niveles predefinidos para cuánto dar o qué profundidad; depende de su reacción real. Anota si expande o contrae contenido, si hace clic en "Explicar" con frecuencia, cuán detalladas son sus notas, qué clics da en la retroalimentación de toda la ronda. Guárdalo en .frame-align/observations.md; antes de generar la siguiente ronda, léelo y menciona en "Qué se está haciendo en esta ronda" qué ajustaste basándote en ello. Solo registra comportamientos y requisitos explícitos; no pongas etiquetas. Él puede ver y modificar este registro.

Si durante varias rondas solo dice "continúa" sin notas, expansiones, preguntas o cambios, primero asume que estás dando demasiado o que es demasiado difícil de juzgar. Responde de lo más ligero a lo más pesado; una vez que él vuelva a participar, retrocede:

1. Reduce la cantidad, cambia la forma de decirlo, saca una o dos decisiones clave por separado. Dile en una o dos frases cómo ha cambiado el marco actual respecto a lo que dijo inicialmente.
2. Pregúntale algo sobre la salida: ¿todo está bien, o estoy dando demasiado o es difícil de juzgar?
3. Si sigue igual y lo que se está decidiendo es importante y está fuera de su experiencia: pídele que primero exprese su inclinación y luego tú das la recomendación.

Si acepta todo pero ha dejado notas, preguntas o cambios, no entra en este caso. Discutir con razones es saludable.

No halagar, no eludir responsabilidad

• Separa hechos de opiniones. Lo que dices, por defecto, es tu opinión; no necesitas etiquetarlo cada vez. Solo etiqueta dos tipos: hechos con fuente (indica la fuente) y cosas que necesitan su decisión (da opciones). No presentes opiniones como hechos, haciéndole creer que no tiene opción.
• Si te cuestionan, verifica. Cuando cuestione un hecho que afirmaste, no cedas ni te aferres; investiga y luego reporta qué investigaste y cuál fue el resultado.
• Toma posición. Para recomendaciones y decisiones que necesita tomar, da una recomendación clara; no solo enumeres pros y contras. Las ideas no necesitan posición en cada una.
• La protección recae en las acciones, no en las palabras. Lo que se puede verificar, verifícalo. Frases como "esto puede no ser exacto" solo tienen sentido si explicas qué intentaste y por qué no pudiste verificar. Dejar escapatorias por doquier te protege a ti, no lo ayuda a él.

Cuando escribas sobre hechos de los que depende el marco, o cuando él te cuestione, lee references/discipline.md.

Salida

Cuando el usuario indique que el marco es válido, primero realiza una verificación de salida y luego pasa al llenado de contenido.

La verificación de salida es obligatoria; su profundidad depende de la situación real de esta alineación. Por defecto, lo más ligero: enumera lo que aún no está resuelto en una página y pídele que lo revise; si no hay tal contenido, infórmalo con una frase y continúa directamente. Qué enumerar y cuándo hacerlo un poco más pesado, consulta references/discipline.md.

Una vez aprobado:

1. Genera el documento del marco. Por defecto, colócalo en framework/framework.md en el directorio de trabajo actual; si él especificó otra ubicación, o el proyecto ya tiene una convención para documentos, sigue esa y guarda la ubicación en el estado. El formato se encuentra en references/state-format.md.
2. En el estado, registra la ronda y hora de salida; si es un repositorio git, también registra el hash del commit, y cambia phase a filling.
3. Dile dónde está el documento y dale una instrucción de inicio directamente utilizable, con un tono como: "Implementa según este documento; si encuentras algo que no coincide, anótalo y dímelo". Con su consentimiento, añade una línea en AGENTS.md o CLAUDE.md del proyecto que apunte a este documento.

Este skill termina aquí. El llenado de contenido sigue tu forma habitual y no está bajo el alcance de este skill.

Rehacer

El marco no se congela en la salida. La implementación inevitablemente revelará cosas que el marco no anticipó; esto es normal, no un fracaso. Rehacer debe ser barato, de lo contrario preferirá arreglárselas.

1. Después de la salida, el documento del marco es la referencia. Primero, lee los cambios que se le hayan hecho de vuelta al estado.
2. Desde .frame-align/rework.md y la razón de esta invocación, solo lee el código y documentos a los que apunten; no releas todo el proyecto.
3. Abre una ronda que solo contenga contenido relacionado con estas inconsistencias: qué nodo debe cambiarse, si el ancla objetivo sigue siendo válida.
4. Luego, procede con el ciclo normal y, al salir nuevamente, actualiza el documento del marco.

Archivos auxiliares

• references/state-format.md: formato del estado, registro, observaciones y documento del marco. Léelo antes de escribir el estado por primera vez.
• references/page-contract.md: cómo iniciar la página, cómo se muestra el estado en la página, qué marcadores hay y el formato del archivo de respuesta. Léelo antes de la primera presentación.
• assets/page.html, scripts/serve.js, scripts/serve.py: página predefinida y servicio de página. Úsalos directamente; no necesitas leer su contenido.
• references/discipline.md: fuentes y verificación, caducidad de archivos, cómo registrar desacuerdos, verificación de salida. Léelo al escribir sobre hechos de los que depende el marco, cuando te cuestionen, o al salir.
• references/lenses.md: lista de perspectivas para marcos de software. Consúltalo al completar.