jasonericsiegel/human-feedback

Retroalimentación Humana

Convierte cualquier página HTML en una que el usuario pueda comentar: un esquema a la izquierda, sus notas a la derecha junto a lo que están viendo, y un botón Copiar: Copiar mi retroalimentación cuando está vacío, Copiar N notas antes de su primera copia, luego Copiar N notas nuevas o Copiar de nuevo. El usuario pega el texto copiado en el chat; tú lo aplicas. Cada pulsación de tecla se guarda en su navegador.

Esta versión no envía contadores de uso.

• Claude Code y Codex pueden cargar este archivo. allowed-tools es un campo de Claude Code; Codex lo ignora.
• $SKILL_DIR significa la carpeta desde donde se cargó este SKILL.md (por ejemplo ~/.claude/skills/human-feedback o ~/.codex/skills/human-feedback); escribe esa ruta literal en los comandos. Cada llamada de shell es un shell nuevo.
• En un sandbox de Codex, add_notes.py abre la página a través de show.py, que maneja Chrome mediante AppleScript y puede necesitar aprobación: pídela en lugar de saltar el paso 3.
• Lo que su página muestra en cada paso (tu cursor, la apertura de cada ronda, Recibido y Hecho) está en references/what-the-user-sees.md: léelo cuando el usuario pregunte cómo se comporta la página.

Cuándo usarlo

• Estás pidiendo al usuario revisar, aprobar o elegir entre trabajo que hiciste (un informe, un plan, un borrador, una maqueta, opciones, reglas propuestas), o ellos piden revisarlo → ponlo en una página aquí, sin que te lo pidan.
• El trabajo aún no es una página → construye HTML simple a partir de él y conserva el archivo original como fuente.
• Una pregunta independiente que no necesita página de revisión se queda en el chat.
• Responde las preguntas del usuario en las Notas. Usa --reply en la nota que hace la pregunta, incluso cuando también pide un cambio. Pon los cambios, explicaciones más largas y tus propias preguntas de revisión en la parte relevante de la página. Usa --ask o --again para una burbuja con tu propia pregunta solo cuando el usuario la pida.
• Una vez que una página está lista para sus notas, y en cada ronda posterior: si inbox-for-human está en tu lista de habilidades disponibles (su nombre, con o sin prefijo de plugin), cárgala con la herramienta Skill (en Codex, abre el SKILL.md al que apunta su lista de habilidades) y pon la página en cola. Si no lo está, di una vez: "Se ejecutó sin la habilidad inbox-for-human, que mantendría esta página en una lista de revisión."

Primer uso

Antes de la primera página en una configuración, ejecuta python3 "$SKILL_DIR/scripts/self_check.py" y pasa su mensaje en palabras simples. No lo vuelvas a ejecutar después de que haya pasado; el script recuerda una verificación superada. --force lo ejecuta de nuevo cuando sea necesario.

Si no puedes ejecutar comandos aquí, no lo intentes. Di exactamente: "human-feedback no puede funcionar en este modo porque no puedo trabajar con archivos en tu computadora aquí. En la aplicación de escritorio de Claude, abre la pestaña Código y selecciona una sesión Local. En la aplicación de escritorio de ChatGPT, cambia a Codex y mantenlo en Local."

Salida 2, o ese mensaje, significa detenerse: no intentes construir una página. Salida 1 da un archivo que el usuario puede abrir por sí mismo para verificarlo.

1. Marca las partes

Pon data-note en cada parte sobre la que el usuario pueda comentar como una unidad: una tarjeta, una sección, una opción, una fila de tabla. Las etiquetas provienen del primer encabezado de la parte, así que un simple data-note suele ser suficiente. Una parte sin encabezado, o cuyo encabezado repite el de otra parte, recibe su propia etiqueta: data-note="Opción B · Calma". Las etiquetas deben ser únicas en la página.

Una página que obtiene sus partes de su propio script también recibe notas sobre ellas, siempre que el script las dibuje de inmediato, no en un evento posterior como DOMContentLoaded o un clic. No las copies en el HTML; el conteo del paso 2 solo cubre las partes escritas allí.

Marca la parte alrededor de una página local mostrada en un <iframe>. El paso 2 etiqueta la página enmarcada para que sus palabras ofrezcan Comentar, Editar y Resaltar. La página de revisión guarda la retroalimentación y nombra la fuente enmarcada en la edición copiada.

Nunca marques texto para que el usuario lo llene o reescriba, y nunca le pidas al usuario que edite la página: el usuario reescribe cualquier línea por sí mismo cuando lo elige, con Editar en la ventana emergente que aparece con un clic o una selección (⌘Z deshace una edición). Haz preguntas en su lugar (paso 6).

No construyas cuadros de comentarios, campos de entrada ni botones de copia propios. La capa hace todo eso.

El esquema a la izquierda ya es la navegación de la página: lista cada parte, muestra los encabezados de sección fuera de las partes como subtítulos, marca la parte en vista y salta a una parte sin la barra superior propia de la página. Antes de darle a la página su propia navegación (pestañas de sección, una lista de contenidos, enlaces de salto, un contador de pasos con anterior y siguiente), juzga qué es más fácil para el usuario, para que el usuario nunca encuentre dos formas de hacer una cosa:

• Solo repetiría el esquema → déjalo fuera. Nombra las partes y los encabezados de sección como lo que sus botones habrían dicho.
• Hace algo que el esquema no puede (un interruptor Oscuro/Claro, un filtro, botones anterior y siguiente que desplazan la página parte por parte) → conserva solo esa parte.
• Muestra partes en pestañas u otros paneles ocultos → conviértelo en una página de desplazamiento único. El usuario pidió pestañas → márcalas y no escribas nada más: un role="tablist" de <button role="tab" aria-controls="…">, cada uno nombrando un role="tabpanel", luego partes data-note dentro de los paneles como de costumbre. La capa cambia los paneles, dibuja una barra adhesiva simple, lista cada pestaña en el esquema como un nivel de su jerarquía, donde se encuentra en la página, mantiene la pestaña abierta entre recargas y versiones, abre una pestaña para una fila del esquema, un stepper o un enlace # hacia él, y retiene un hilo hasta que su pestaña se abra. Una página con su propio script de pestañas lo conserva, y un tablist con una class mantiene el estilo propio de la página.
• Cada página obtiene versiones desde su segunda ronda (paso 5) → no vincules las teclas ← y →; el stepper de versiones las usa.

Puntos de integración, para cualquier página que aloje la capa (una página hecha por otra habilidad, o a mano):

• Las partes data-note alimentan el Esquema y la columna de notas, como arriba.
• data-notes-layer se establece en <html> una vez que la capa se ha dibujado, y está ausente en una página sin ella. Una página anfitriona lo usa para ocultar su propio esquema, o una línea que solo tiene sentido sin la capa, para que el usuario nunca vea dos: html[data-notes-layer] .su-esquema { display: none; }. Nada desactiva la capa, por lo que el marcador permanece. No confíes en nada más que la capa agregue.

2. Activa las notas

python3 "$SKILL_DIR/scripts/add_notes.py" <pagina.html> --agent "Claude"

Agrega una etiqueta justo antes de </body>, imprime el conteo de ronda y partes, y abre la página a través de show.py. Las re-ejecuciones, --next-round y la ejecución de seguimiento de una nueva versión también la abren; --new-version solo, --received y --converged no. Si la apertura falla, la página permanece lista y la ejecución imprime por qué y el comando para abrirla manualmente. En una primera ronda también coloca un pequeño estilo en el head de la página, que mantiene la página oculta hasta que la capa la dibuja. Re-ejecutar reemplaza la etiqueta, así que ejecútalo de nuevo después de reescribir la página. Una advertencia sobre partes faltantes o una etiqueta duplicada → arregla las marcas y vuelve a ejecutar.

• --hold: prepara la página sin abrirla, mientras la construyes o verificas, o cuando el usuario pide solo un enlace (paso 3).

• --pictures off: desactiva los archivos adjuntos de imágenes para una página compartida con otras personas o una construcción pública; las ejecuciones posteriores mantienen la configuración.

• --agent: tu nombre como la gente lo conoce. Claude Code pasa Claude, Codex pasa Codex, cualquier otro agente su propio nombre de producto. Un cursor que lleva ese nombre y tu logo hace tu parte en su página: escribe tus mensajes y hace clic en los estados de su barra de notas (Recibido y Actualizando en el paso 4, Hecho en el paso 8). Las ejecuciones posteriores mantienen el nombre, así que pásalo la primera vez.

• --helper "<nombre>" y --owns "<nombre>:[Etiqueta de parte]": otro agente hizo partes de la página (un subagente que enviaste, Codex, cualquiera que no seas tú). Nombra a cada ayudante una vez, como la gente lo conoce, y cada parte que hizo con --owns, la etiqueta como la muestra el Esquema; ambos se repiten, máximo tres ayudantes. Tú sigues siendo el líder (--agent). En la página, el cursor de cada agente hace solo lo que posee. Las ejecuciones posteriores los mantienen; una ejecución con cualquiera de las banderas los reemplaza; una nueva versión comienza sin ninguno, así que pásalos de nuevo en su ejecución de seguimiento cuando sus partes aún sean suyas. Tú lo hiciste todo → deja ambos fuera.

  python3 "$SKILL_DIR/scripts/add_notes.py" <pagina.html> --agent "Claude" --helper "Codex" --owns "Codex:[Opción B · Calma]"
  

• --workspace <dir>: tu espacio de trabajo (la carpeta del proyecto en la que trabajas). Cada ejecución crea <dir>/human-feedback/attachments/ si falta, con un archivo marcador en human-feedback/; la página guarda allí las imágenes que el usuario adjunta, después de que el usuario seleccione esa carpeta human-feedback una vez en Chrome, y los avisos de la página te nombran ("En la carpeta del espacio de trabajo de Claude, selecciona la subcarpeta human-feedback…"). Sin esto: el repositorio de la página, o si no, el repositorio de tu directorio actual, o si no, el directorio actual. Las ejecuciones posteriores mantienen la carpeta que nombra la etiqueta.

• La página se sirve a través de http (usa fetch, módulos o activos ../) → agrega --copy, que coloca human-feedback.js junto a la página. Las ejecuciones posteriores, reescrituras y nuevas versiones lo mantienen, y lo indican.

• Nunca pegues ni incluyas human-feedback.js en la página, y nunca lo leas: la etiqueta es todo lo que la página necesita.

• Pon las preguntas sobre la página en la parte que les concierne (paso 6).

Apariencia

• Sigue la apariencia del sistema por defecto. Ofrece Automático, Claro y Oscuro cuando el material bajo revisión es prosa en los estilos de lectura compartidos, o cuando el usuario pide el control. Déjalo apagado en otras revisiones.
• Al ofrecer el control, usa --appearance page si la columna de lectura ya tiene ambas paletas y puedes verificar ambas. Reutilízalas en la misma página. Para una página con un tema independiente, sin una paleta probada, o cuya apariencia es parte de la revisión, usa --appearance sidebars para cambiar el Esquema y las Notas solo. Mantén las capturas de pantalla y los elementos incrustados como están.
• En el CSS de la columna de lectura, html[data-notes-layer="light"] y html[data-notes-layer="dark"] son las opciones explícitas. Mantén la consulta de medios del sistema para Automático y cuando la página se abre sin la capa. La elección del usuario permanece con esta revisión a través de las rondas. Otras revisiones comienzan en Automático.
• Una re-ejecución o una versión copiada por --new-version mantiene la configuración. Pasa --appearance off para eliminar el control, o pasa la configuración deseada de nuevo al reconstruir el archivo desde cero.

3. Muéstralo

Para cualquier tipo de revisión, en cada ronda:

• Una vez que la revisión esté lista, ábrela en el navegador del usuario en cada ronda. El abridor reutiliza la pestaña existente en Chrome cuando encuentra una ronda anterior allí. Usa --hold mientras construyes o verificas la página, o cuando el usuario pide explícitamente solo un enlace.
• Para una revisión local, termina con add_notes.py sin --hold. Las nuevas revisiones en una carpeta dedicada cuyos activos viven en esa carpeta usan una dirección web local para todas las rondas, por lo que el navegador mantiene el zoom de la página y las notas. Mantén las rondas y sus activos en esa carpeta o sus subcarpetas y usa rutas de activos relativas. Proporciona el enlace de la dirección de revisión que imprime el abridor.
• Para una página ya servida a través de HTTP, prepárala con --hold --copy y ejecuta show.py <pagina local.html> --preview-url <URL HTTP de la nueva ronda>. Mantén el mismo servidor de vista previa a través de las rondas para que el abridor pueda encontrar la pestaña existente y el navegador mantenga las notas del usuario.
• Pon el enlace de la página en tu respuesta cada ronda. Usa el formato de enlace de tu proyecto, con el resultado del abridor para decir dónde está la página. Si el abridor falla o dice que dejó la página cerrada, dilo y proporciona el enlace.
• Una página cuyas rondas o versiones anteriores el usuario abrió desde file:// → sigue mostrándola desde file:// (show.py en su ruta) y no des un enlace localhost, incluso si el proyecto pide uno: el navegador mantiene las respuestas del usuario por dirección, por lo que una copia localhost no muestra ninguna de ellas y reabre hilos que cerraron. Di en la respuesta por qué no hay enlace.

Haz esto solo una vez que la página esté lista para sus notas.

Ejecuta add_notes.py sin --hold una vez que la página esté lista para sus notas. Termina el contenido de la página y marca cada parte primero. Pasa cualquier marca de hecho y cualquier burbuja que el usuario solicitó en esa ejecución (la ejecución de seguimiento del paso 5 para una nueva versión).

Una corrección que le dijiste al usuario que está en camino también retiene la siguiente versión. Muéstrala una vez que esa corrección esté activa.

Para una verificación, prepárala con --hold, luego verifícala tú mismo (o haz que un subagente la capture) con la capa de notas activada, ya que la capa estrecha la página, y corrige lo que encuentres. Tus mensajes (preguntas, respuestas) llegan solo una vez que la pestaña tiene el foco, y un navegador sin cabeza nunca lo enfoca a menos que la emulación de foco esté activada (tests/harness.mjs la activa). Sin ella, verifica los mensajes en los datos de la etiqueta en su lugar, y la página misma permanece en blanco detrás de su apertura: tómala con shoot_page.py de reading-page-formats, que captura y luego elimina una copia limpia sin la etiqueta y su estilo de retención. Esa copia limpia ocupa toda la ventana, pero en su pantalla las columnas de notas ocupan aproximadamente 375px a cada lado (medido a 2560 de ancho, 2026-11-01). Así que tómala también a ese ancho más estrecho, y corrige cualquier ajuste o desbordamiento antes de mostrarla. Una copia limpia no puede mostrar las columnas cubriendo la página, así que también carga la página retenida con la capa activada y verifica que document.querySelector('h1').getBoundingClientRect().left esté a la derecha del borde del esquema; el primer elemento de texto servirá en una página sin h1. Solo entonces abre la página usando el comando local o HTTP anterior. Dile al usuario que está lista para sus notas, dónde está (la línea que imprime el abridor), y que pegue lo que Copiar le da. Si hiciste preguntas o dejaste respuestas, di cuántas están esperando en la página.

Una vez que se muestra una página, mantén el chat en la línea de listo, el enlace y cualquier cosa que impidió que la página se abriera o la línea requerida de otra habilidad. Pon cambios, hallazgos, fuentes, salvedades, verificaciones y preguntas en las partes que les conciernen. Usa el propio Más información de la página para fuentes y detalles cuando lo tenga.

Una página que enmarcaste lleva la etiqueta del marco también, por lo que abierta por sí misma muestra las columnas de notas y se comprime, y una verificación de ella reporta defectos falsos. Verifícala desde una copia limpia en tu bloc de notas en su lugar: quita el estilo de retención y la etiqueta, o borra directamente desde un duplicado sin ellos.

... [truncado para traducción]