2D0/claude-skills

blackbox

Resumen

Una caja negra es el registrador de vuelo de un elemento: un registro de decisión no resumido por cada unidad de cambio aprobada por el propietario — lo que el propietario realmente dijo (textualmente), qué significó en contexto, qué recomendó y construyó el asistente, por qué, la evidencia que impulsó cada elección, y qué errores cometió el asistente en el proceso — anclado al contenido que explica y leído solo bajo demanda. Existe para que una sesión futura audite el origen de una regla en lugar de re-litigarla.

Dos cosas que no es:

• No es un transcript. Seleccionar no es resumir. La entrada se escribe a partir del rastro de decisiones, no del registro de chat: se omiten enseñanzas, analogías y desvíos que ayudaron al propietario a entender pero que no cambiaron ninguna decisión. Lo que se conserva se conserva completo.
• No es un diario sobre el propietario. Registra lo que se dijo y decidió, no quién es el propietario. Las observaciones sobre el estilo de trabajo pertenecen a la memoria del asistente, nunca aquí.

¿Este elemento tiene una caja negra?

• blackbox/README.md está al lado del elemento (o en la raíz del repositorio) → la convención aplica. Lee ese README Y la entrada más reciente antes de escribir la tuya — el esquema proviene de ellos, nunca de tu cabeza.
• Sin marcador, y el propietario solicita adoptar uno → inicializa: copia blackbox/README.md del directorio de este skill al elemento, sin cambiar nada excepto el nombre del elemento, luego registra la adopción misma como la primera entrada.
• Sin marcador, y estás a punto de editar un documento de especificación / convención / diseño por primera vez en esta sesión → busca el marcador. Si está ausente, ofrece la adopción una vez, en una oración, luego continúa con la tarea del propietario. La adopción es decisión del propietario; si decline, anótalo en la memoria para que no se le pregunte de nuevo al repositorio.

La unidad de adopción es el directorio que contiene el marcador — un skill, un paquete o un repositorio completo. Cualquier repositorio, cualquier método de fusión.

Unidad y momento

• Una entrada por unidad aprobada por el propietario: una especificación confirmada, un PR fusionado, una convención revisada. No por commit, no por turno de conversación. Una unidad que produjo varios commits recibe una entrada.
• Escrita en la sesión donde ocurrieron las decisiones. El intercambio en bruto vive solo en el contexto actual; una vez que la sesión termina, solo sobreviven los resúmenes y las citas textuales se pierden. Si una unidad se alarga o abarca varias sesiones, guarda un borrador temprano — Refs: pendiente, citas del propietario e índice completados — y finaliza (ancla los blobs, completa el cuerpo) en la aprobación. Un borrador es mejor que una memoria reconstruida.

La receta (por unidad aprobada por el propietario)

1. Haz el cambio.
2. Ancla los resultados por contenido. Para cada archivo modificado, ejecuta git hash-object <ruta> en el árbol de trabajo. Los SHA de blob están direccionados por contenido — los mismos bytes generan el mismo hash para siempre, por lo que el ancla sobrevive a squash, rebase y cualquier reescritura del historial, y existe antes de cualquier commit.
3. Escribe la entrada blackbox/AAAA-MM-DD-<slug>.md con la siguiente forma: un índice que apunta al cuerpo, luego el cuerpo en bruto.
4. Fusiona la entrada con el cambio — mismo commit o mismo PR, fusionado como el repositorio normalmente fusiona.

Verifica un ancla: git hash-object <ruta> y compara. Recupera un estado anclado: git log --find-object=<sha> o la API de blobs de GitHub.

Regla de lectura: nunca cargues blackbox/ durante el trabajo normal en el elemento. Léelo solo para preguntas de procedencia.

Forma de la entrada

# AAAA-MM-DD — <título>

Refs:           <ruta> @ blob <sha>            (una línea por archivo modificado)
Decisions:      <decisión> <peso> [→ <nuevo peso>, ver §…] · …
Reversals:      §… · §…   (o: ninguna)
Owner caught:   §… · …    (o: ninguna)
Declined:       §… · …    (o: ninguna)
Evidence:       <comando / número / enlace> · …
Understanding:  §…        (o: n/a)
---
<cuerpo en bruto, con encabezados § a los que apunta el índice>

Las líneas del índice apuntan al cuerpo; nunca lo reemplazan.

• Decisions — cada decisión que contiene la unidad, con el peso que el asistente asignó al preguntar (🔴 debe decidir ahora · 🟡 decidir, revisable · 🟢 tomar la recomendación). Si un peso se cambió posteriormente, indícalo y señala por qué. Con el tiempo, esta línea es cómo el propietario audita su propia deliberación contra el peso que la decisión merecía.
• Reversals — cualquier cosa que el asistente afirmó y luego retiró o corrigió: una afirmación incorrecta, una recomendación revertida por medición, una decisión que tomó sin preguntar. ninguna es un valor válido y debe escribirse explícitamente.
• Owner caught — inconsistencias o fallos que el propietario detectó (un conteo incorrecto, un elemento faltante, un error estructural). La auditoría del propietario, no solo la del asistente.
• Declined — opciones, valores predeterminados de herramientas o recomendaciones externas deliberadamente no tomadas, con la razón en el cuerpo.
• Evidence — lo que realmente se consultó al decidir: el comando ejecutado, los números que produjo, la página o archivo mostrados. Registra la reproducción, no la imagen — un diagrama se regenera a partir de su comando; una captura de pantalla no.
• Understanding — cuando el propietario aprobó mientras decía que no entendía completamente, su declaración y lo que debe reexplicarse después.

Idioma

• Cuerpo: inglés, independientemente del idioma de los documentos del repositorio.
• Entrada del propietario: el original textual, luego una reescritura en inglés. Primero el texto textual, en un bloque de cita >, exactamente como se escribió — errores tipográficos, abreviaturas, ㅇ y todo. Luego la reescritura: completa en contenido, natural en forma, autocontenida (un lector sin otro contexto la entiende). El texto textual es la evidencia — un error tipográfico que cambió una decisión solo puede encontrarse allí. La reescritura es la lectura del asistente en ese momento — si ambos están en desacuerdo, la entrada ya ha registrado la falla.
• Respuestas del asistente, fundamentos y procesamiento interno: inglés, en forma completa para cualquier cosa que afecte a una decisión. > ㅇ seguido de El propietario aprobó la opción (a). es un registro completo; no lo rellenes.

Formas estrictas

Regla	No esto
Entrada del propietario = cita textual y reescritura en inglés	Solo texto textual (ilegible sin contexto), solo reescritura (evidencia perdida) o un resumen de una línea
Índice arriba, cuerpo en bruto abajo, líneas del índice apuntando a encabezados §	Un índice que resume en lugar de apuntar; un cuerpo sin índice; secciones llenas de frases de una línea
Cuerpo extraído del rastro de decisiones	Enseñanzas, analogías o desvíos que no cambiaron ninguna decisión
Reversals: presente, incluso como ninguna	Una entrada que enumera solo lo que salió bien
Refs: = SHA de blob por archivo (git hash-object)	Un número de commit o PR como ancla — las reescrituras del historial los destruyen
La entrada se fusiona en el mismo commit o PR que el cambio	Un PR de seguimiento "más tarde"
Escrita en la sesión donde ocurrieron las decisiones	Reconstruida la próxima sesión de memoria
Esquema de entrada desde el README y la entrada más reciente	Un formato inventado

Banderas rojas

• Una entrada sin línea Refs:, o un Refs: que nombra un commit o PR en lugar de blobs
• Una entrada del propietario sin cita textual >, o una cita sin reescritura después
• Sin línea Reversals: en absoluto
• Líneas del índice que se leen como resúmenes en lugar de punteros
• Un cuerpo que explica conceptos al lector en lugar de registrar lo que se decidió
• Un cambio fusionado sin su entrada
• Una entrada escrita en la sesión después de las decisiones que registra (indícalo en la entrada si es inevitable)

Procedencia

blackbox/ contiene el registro completo de decisiones para este elemento — entradas del propietario (textual + reescritura en inglés), razonamiento del asistente, evidencia y reversiones, ancladas por contenido por cambio aprobado. Léelo solo cuando investigues por qué existe una regla o qué pidió originalmente el propietario. Nunca lo cargues durante el uso normal.