oliverswitzer/lens

Lente

Un lente es un grafo JSON, <lente>/model.json, compilado en un <lente>/index.html auto-contenido que cualquiera puede abrir y comentar. <lente> es la carpeta donde se creó (por defecto docs/lens). <lente>/README.md documenta los tipos de nodos, relaciones, forma de las afirmaciones y reglas de integridad. La compilación rechaza un modelo que incumpla una regla, por lo que una compilación verde es la primera verificación.

La carpeta de este skill contiene template/ (lo que se copia en un repositorio), scripts/ (ayudantes para competidores) y competitors.md. Se encuentra en .claude/skills/lens/ del repositorio, o en ~/.claude/skills/lens/ cuando se instala globalmente; a continuación, $SKILL significa esa carpeta.

Requisitos: Node 20+ y git. Sin package.json, sin dependencias.

Crear un nuevo lente

1. Elegir la carpeta. Preguntar al usuario dónde debe vivir el lente; por defecto docs/lens. Rechazar sobrescribir un model.json existente allí.

2. Copiar la plantilla (todo excepto un index.html compilado):

   mkdir -p docs/lens && cp -R "$SKILL/template/." docs/lens/ && rm -f docs/lens/index.html
   echo '[]' > docs/lens/ids.lock.json      # los ids iniciales no son tuyos; comienza el bloqueo vacío
   

3. Entrevistar al usuario, luego reemplazar el modelo inicial. model.json incluye un ejemplo ficticio "Acme Notes" que muestra todos los tipos comunes. Mantén su forma, reemplaza su contenido. Pregunta, un tema a la vez, y da un borrador concreto para corregir en lugar de una pregunta en blanco:

   • el nombre del producto (title) y el nombre del dueño (el nodo persona owner, id p-owner a menos que prefieran otro; su title se muestra como "’s view" en cada afirmación de tipo view);
   • el propósito en una oración (purpose, una afirmación view que cita la fuente del dueño);
   • el ciclo principal, de 2 a 5 loop-steps ordenados;
   • para quién es (avatars, con un mapa de persona), y qué les duele (problems);
   • entrevistas u otra evidencia que ya tengan (nodos source + person; nunca inventar citas ni marcas de tiempo — si no hay transcripción, registrarlo como reporte del dueño);
   • lo que se ha enviado (surface, shipped: true, con una captura de pantalla real) y lo que es solo una idea (shipped: false);
   • qué usa la gente en su lugar (alternatives);
   • hasta tres apuestas para probar ahora (nodos hypothesis con focus: 1|2|3). Todo lo que el usuario dice sin evidencia es un view (su opinión) o un hypothesis; nada es observed sin una fuente y un at. Usa nombres genéricos ("Entrevistado A") a menos que el usuario quiera nombres reales en un archivo que puede ser público.

4. Limpiar el ejemplo. Eliminar assets/example.png una vez que ningún nodo lo referencie, y apuntar las capturas de pantalla a assets/surfaces/<surface-id>/<slug>.png. Las rutas code y adrs de las superficies son relativas a la raíz del repositorio y deben existir (apunta adrs a donde el repositorio guarda los registros de decisiones, p. ej. docs/adr/).

5. Compilar y probar:

   node docs/lens/build.mjs && node --test docs/lens/tests/*.test.mjs
   

6. Verlo. Los comentarios se almacenan en el navegador por origen, así que sírvelo en lugar de abrir el archivo directamente:

   python3 -m http.server 8767 --bind 127.0.0.1    # desde la raíz del repositorio
   open "http://127.0.0.1:8767/docs/lens/index.html"
   

7. Sugerir una línea .gitignore para docs/lens/assets/ads/**/*.mp4 si van a rastrear anuncios de competidores. Hacer commit de model.json, ids.lock.json, index.html, assets/ y el resto de la carpeta, siguiendo las reglas de commit del repositorio.

Fundamentar el trabajo

Leer los nodos relevantes, sus afirmaciones y sus fuentes antes de preguntar al dueño cualquier cosa. Darles una síntesis concreta para corregir. Para una superficie, verificar el código que nombra (code, adrs) cuando su comportamiento importa; un registro de decisión dice lo que se decidió, no lo que el código hace hoy.

Agregar evidencia

Cada declaración es una afirmación con kind, evidence y un next opcional:

• observed (Oído / visto): lo que alguien dijo o hizo. Citar la fuente con at (una marca de tiempo de una transcripción, o una sección para un documento). Citar o parafrasear con precisión; nunca mejorar una expresión de duda ("podría ser útil").
• view (Opinión del dueño): la interpretación del dueño. Debe citar una fuente cuyos people incluyan al owner del modelo.
• hypothesis (Sin probar): cualquier cosa no probada, incluyendo sugerencias del agente e ideas de implementación.
• Una hipótesis también es un tipo de nodo: registrar cada pieza de evidencia con stance (supports o contradicts) y at. Nunca establecer una confianza; el medidor en las hipótesis focus se calcula a partir de esa evidencia en la próxima compilación (entrevistados distintos que la apoyan; un escalón abajo si alguien la contradice; la opinión del dueño nunca la aumenta). Registrar evidencia contradictoria con la misma disposición que la de apoyo.
• Dar a cada afirmación débil un next: una pregunta lo suficientemente específica para hacer en una llamada. Aparece en Próxima conversación.
• Mantener claro quién lo dijo: una idea que el dueño planteó y alguien aceptó no es su necesidad.
• Una nueva entrevista es un source con date, people, locator y takeaways cortos, citados por las afirmaciones que apoya. Dejar fuera los detalles personales no relacionados con el producto. Archivar las transcripciones en <lente>/sources/ solo si el repositorio es privado y el entrevistado estuvo de acuerdo.

Actualizar una superficie (después de cambiarla)

Cuando un cambio altera la apariencia o el comportamiento de una superficie, en la misma rama:

1. Capturar el/los estado(s) cambiado(s) del producto en ejecución en <lente>/assets/surfaces/<id-superficie>/<slug>.png (reemplazar los obsoletos, mantener 1–4).
2. Actualizar las entradas screenshots de la superficie: caption, capturedAt (hoy), origin: "app", version. La página marca cualquier captura más antigua que el último commit en el code de la superficie.
3. Actualizar unique / situations si el comportamiento cambió, y code / adrs si los archivos se movieron.

Una superficie nueva enviada es un nuevo nodo surface con shipped: true, al menos una captura de pantalla, aristas serves a los problemas que aborda y aristas implements a pasos del ciclo.

Agregar una idea (de una lluvia de ideas)

Una superficie que se ha discutido pero no construido es un surface con shipped: false; aparece bajo Ideas, visualmente distinto. Darle unique (como afirmaciones hypothesis), situations, heard (lo que la gente dijo, con evidencia) y mockups como screenshots con origin: "design". Cuando se envíe, cambiar shipped y reemplazar mockups con capturas reales.

Agregar un pilar de contenido o idea

Un tema de marketing es un pillar; un post, video o evento concreto es un content-idea under él, con un format. Enlazar pilares o ideas speaks-to a avatares, las ideas features las superficies que muestran y like a competidores que ya ejecutan un ángulo similar. Las ideas y pilares están Sin probar hasta que el contenido haya llegado a personas; registrar lo que sucedió como evidencia en una hipótesis about la idea.

Agregar una información de mercado

Una tendencia de investigación externa es un insight en la pestaña Información de mercado. Registrar el artículo como una fuente Market research (opcionalmente una instantánea en sources/), indicar sus hechos como hallazgos observed, y mantener lo que significa para un avatar como una opinión o hipótesis, incluyendo un hallazgo sobre los límites de la fuente. Enlazarlo bears-on a todo lo que afecta.

Agregar o actualizar un competidor

Seguir $SKILL/competitors.md: investigar (verificaciones de anuncios en navegador real, nunca evadir un muro), scripts/add-product.py, captura de anuncios preparada, scripts/apply-staged-ads.py (verifica todo, luego aplica en un solo paso), scripts/smoke-ads.mjs, luego hacer commit sin .mp4s. Comparar con el producto desde el propósito del lente y las hipótesis de enfoque, nunca con su página de marketing, y etiquetar esa comparación como Sin probar.

Los hallazgos de usabilidad no son contenido del lente

Los problemas de interacción (un botón que nadie encuentra, un estado de foco faltante) pertenecen al rastreador de incidencias del equipo. Archívalos allí y registra solo su significado para el producto, si lo hay, en el lente.

Renombrar o eliminar

ids.lock.json registra cada id comentable de la última compilación. Un id que desaparece debe mapearse en el campo renamed de model.json ("old-id": "new-id", o null cuando se elimina intencionadamente), o la compilación falla. Esto es lo que mantiene adjuntos los comentarios existentes.

Cambiar el lente en sí mismo

Cualquier cambio en components/ (lo que muestra una vista, enrutamiento, validación, la diferencia) comienza con una prueba fallida en <lente>/tests/ (node:test; fixture compartido en tests/fixture.mjs, solo nombres ficticios). Mantener la lógica en módulos puros; solo components/app.js toca el DOM. Luego ejecutar las pruebas, luego verificar el mismo escenario en un navegador.

Visualizar la diferencia

Cuando el dueño pida ver, revisar o visualizar qué cambió:

node docs/lens/diff.mjs [rev]          # por defecto HEAD; imprime la lista de cambios
python3 -m http.server 8767 --bind 127.0.0.1
open "http://127.0.0.1:8767/docs/lens/index.html"

Los contornos verdes son elementos añadidos y los amarillos son elementos cambiados; los elementos eliminados se muestran en rojo en el banner. Cada fila añadida o cambiada enlaza a su elemento. Los cambios se emparejan por id, por lo que una sola afirmación se ilumina sin toda su tarjeta. Antes de hacer commit, siempre limpiarlo y verificar:

node docs/lens/build.mjs
grep -c LENS-V2-DIFF docs/lens/index.html   # debe imprimir 0

Recompilar y verificar

node docs/lens/build.mjs && node --test docs/lens/tests/*.test.mjs

Luego mirar las vistas afectadas en el navegador. Los comentarios son locales al navegador del origen; exportarlos antes de cambiar. Terminar con el enlace del lente, qué cambió, la evidencia y cualquier límite.