CommunityRedacción y edicióngithub.com

Blindspot Audit

Una habilidad portátil para agentes de IA que identifica puntos ciegos, riesgos ocultos y decisiones faltantes en proyectos, con un registro duradero para auditorías repetibles en Claude Code, Codex y OpenCode.

¿Qué es Blindspot Audit?

Blindspot Audit es una habilidad especializada para agentes de IA (como Claude Code, Codex y OpenCode) que ayuda a los desarrolladores a encontrar brechas entre su comprensión actual de un proyecto y la realidad del mismo. En lugar de ser una lista de verificación genérica, esta habilidad aplica un marco de 'cuatro desconocidos' (conocidos conocidos, conocidos desconocidos, desconocidos conocidos y desconocidos desconocidos) para clasificar los hallazgos y priorizar los puntos ciegos más impactantes. Soporta múltiples modos de auditoría (rápido, profundo, entrevista, post-implementación y planificación) y se adapta a diferentes superficies de anfitrión, desde clientes capaces de elegir hasta hosts solo de chat. La habilidad incluye un ledger duradero que permite auditorías repetibles sin repetir hallazgos, y utiliza referencias externas y escaneos de 'ojos frescos' para detectar cambios invisibles en el repositorio, como nuevas regulaciones o cambios en plataformas. Su objetivo es que el propietario del proyecto descubra al menos un punto ciego que no sabía que existía, y que se sienta más tranquilo al saber qué puede ignorar de manera segura.

Compatible con✓Claude Code✓Codex CLI~Cursor✓OpenCode
npx skills add MJL-ren/blindspot-audit

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Blindspot Audit?

Propósito

Encontrar la brecha entre el mapa que el usuario tiene de un proyecto y el territorio real del proyecto. Convertir desconocidos desconocidos en desconocidos conocidos concretos que el usuario pueda inspeccionar, responder, probar o posponer intencionalmente.

El contexto de un proyecto se selecciona a sí mismo: el propietario solo puede escribir lo que ya sabe, por lo que cada README, TODO y plan codifica el mapa que llevan en su cabeza, y una IA que trabaja a partir de esos archivos hereda los mismos puntos ciegos. Esta auditoría importa deliberadamente marcos de referencia desde FUERA del proyecto para medir esa brecha.

Esta habilidad no es una lista de verificación de calidad genérica. Debe identificar lo que es inusualmente importante para este proyecto específico, en esta etapa específica, con evidencia del repositorio o los artefactos proporcionados. La auditoría tiene éxito cuando el propietario dice "Ni siquiera sabía que debería estar pensando en eso" al menos una vez, Y se siente más tranquilo después, porque ahora también sabe lo que puede ignorar de manera segura.

Modelo Central

Clasifique los hallazgos con el marco de los cuatro desconocidos:

  • Conocidos conocidos: lo que ya indican el prompt, los documentos, el código o los planes.
  • Conocidos desconocidos: preguntas abiertas ya visibles en documentos, TODOs, planes, comentarios o redacción del usuario.
  • Desconocidos conocidos: cosas que el usuario reconocería si se le mostraran, pero que no ha verbalizado ni escrito aún.
  • Desconocidos desconocidos: conceptos faltantes, restricciones ocultas o preguntas no formuladas que la forma del proyecto implica.

El marco importa porque la prescripción difiere: un desconocido conocido necesita una línea de lista de verificación, no una conferencia; un desconocido desconocido necesita una breve explicación y el primer paso más económico. Un buen resultado no reclama certeza. Expone candidatos y da el siguiente paso más económico.

Reglas Básicas

Estas existen porque el modo de fallo de esta habilidad no es "perder una brecha", sino convertirse en una molestia genérica de lista de verificación que se ignora.

  1. Los documentos de seguimiento del proyecto son un filtro, no una fuente de hallazgos. Cualquier cosa que ya esté en el README / TODO / hoja de ruta / lista de verificación / lista de problemas es un CONOCIDO desconocido. Nunca lo reporte como un descubrimiento. (Dato de campo: este filtro típicamente reduce la lista de candidatos en más de la mitad y es la razón principal por la que los propietarios confían en el informe).
  2. Limite los principales hallazgos a 3-7, clasificados por impacto x probabilidad de que el propietario sea realmente inconsciente. El exceso va a una breve "Lista de vigilancia de baja señal" o al ledger, nunca a la lista principal.
  3. La ausencia por sí sola no es un hallazgo. "No tienes X" solo cuenta si puedes declarar la consecuencia concreta para ESTE proyecto y el primer paso más económico para cerrarla.
  4. Incluya siempre las dos secciones de confianza: "Verificado y bien cubierto" y "Saltable por ahora" (cada salto con un desencadenante de re-verificación explícito). Previenen la ansiedad y el re-escaneo, y son cómo el propietario aprende que se puede confiar en el informe.
  5. Cubra los dominios regulados. Para hallazgos legales, fiscales o regulatorios, indique lo que encontró y su fuente, luego diga claramente que un profesional debe confirmarlo. Usted es un explorador, no un abogado o contador.

Modos

  • rápido: leer documentos e inventario del proyecto, devolver los puntos ciegos principales.
  • profundo: inspeccionar rutas de código representativas, pruebas, configuraciones y documentos antes de clasificar los hallazgos.
  • entrevista: hacer una pregunta a la vez cuando la respuesta cambiaría la arquitectura, flujo de trabajo, alcance o riesgo.
  • post-implementación: comparar un cambio completado, notas, diferencias y pruebas para encontrar desconocidos restantes.
  • planificación: antes de la implementación, sacar a la superficie decisiones que probablemente cambien modelos de datos, interfaces, flujos de UX, operaciones o verificación.

Infiera el modo a partir de la redacción del usuario. Si el usuario pide ejecutarlo ahora, no haga preguntas de modo a menos que el límite de la auditoría sea imposible de inferir.

Inicio Rápido

  1. Identifique la raíz del proyecto y el límite de la auditoría.
  2. Ejecute el ayudante de inventario cuando un proyecto de sistema de archivos esté disponible. El script vive en la propia carpeta de esta habilidad: resuélvalo relativo a este SKILL.md:
python <carpeta-de-esta-habilidad>/scripts/project_inventory.py <raíz-del-proyecto> --format md

Use --include-generated solo cuando las salidas en tiempo de ejecución, informes generados, registros o artefactos en caché sean parte de la pregunta de auditoría.

  1. Lea solo las referencias relevantes:
    • references/archetypes.md: elija el tipo de proyecto y los puntos ciegos esperados.
    • references/lenses.md: derive y aplique lentes de auditoría.
    • references/host-surfaces.md: adapte preguntas y salidas a Claude Code, Codex, OpenCode, CLI o superficies solo de chat.
    • references/ledger-lifecycle.md: descubra, cree, enrute o actualice un ledger de puntos ciegos duradero.
    • references/report-template.md: formatee el resultado.
  2. Descubra o inicialice el ledger de puntos ciegos:
    • Si existe un ledger anterior, léalo antes de buscar (se aplican reglas de ejecución diferencial - consulte Ledger y Ejecuciones Diferenciales).
    • Si no existe un ledger y el anfitrión puede escribir archivos, cree BLINDSPOT_LEDGER.md en la mejor ubicación de documentación local del proyecto a menos que el usuario haya solicitado salida de solo lectura/solo chat.
    • Si no existe un ledger y el anfitrión no puede escribir archivos, incluya la ruta propuesta y la primera entrada del ledger en el informe.
  3. Inspeccione los archivos de evidencia más fuertes del inventario: README/AGENTS, planes, configuraciones de paquetes, puntos de entrada de la aplicación, configuraciones de prueba, CI, ejemplos de entorno, esquemas, prompts, archivos de agente/habilidad y documentos de tiempo de ejecución.
  4. Ejecute el escaneo externo de ojos frescos (consulte el paso 5 del Flujo de Trabajo) cuando el anfitrión tenga acceso web.
  5. Clasifique los hallazgos, entreviste al propietario cuando sea posible, produzca el informe y actualice el ledger.

Política de Superficie del Anfitrión

El núcleo de la auditoría debe funcionar igual en Claude Code, Codex, OpenCode, CLI y chat simple. Solo el estilo de interacción cambia. Consulte references/host-surfaces.md para detalles por anfitrión.

  • Anfitriones capaces de elegir (Claude Code AskUserQuestion, OpenCode question): cuando una decisión cambie la arquitectura, flujo de trabajo, alcance o riesgo - y para la entrevista de conciencia del propietario - haga una pregunta corta de 2-3 opciones y registre la opción seleccionada en el informe o ledger.
  • Anfitriones Codex o solo chat: no se detenga en preguntas no críticas. Continúe con la suposición reversible más segura, márquela como una suposición e incluya un Paquete de decisión con las opciones que el usuario debe elegir más tarde.
  • Anfitriones sin acceso web: omita el escaneo externo de ojos frescos, dígalo explícitamente en el informe y marque los dominios sensibles al tiempo (regulación, política de plataforma, precios) como no verificados en lugar de afirmarlos desde el conocimiento de entrenamiento.
  • Anfitriones que escriben archivos: para auditorías de proyectos, cree o actualice un ledger por defecto a menos que el usuario haya solicitado salida de solo lectura/solo chat. Mencione la ruta y la edición de enrutamiento en el informe.
  • Anfitriones de solo lectura o de uso público: devuelva un informe portátil con comandos/verificaciones que el usuario pueda ejecutar.

Pregunte de inmediato solo cuando continuar sería arriesgado, destructivo, costoso o probable que produzca resultados engañosos.

Ledger y Ejecuciones Diferenciales

Primera ejecución:

  1. Elija la mejor ubicación duradera para BLINDSPOT_LEDGER.md usando references/ledger-lifecycle.md.
  2. Cree el ledger desde templates/BLINDSPOT_LEDGER.md cuando las escrituras de archivos sean apropiadas.
  3. Agregue el ledger a la superficie de enrutamiento más cercana, como un README de operaciones, índice de documentos o puntero de traspaso, cuando ese archivo de enrutamiento ya exista.
  4. Registre el alcance de la auditoría, modo, límites de evidencia y primeros hallazgos.

Cuando un proyecto ya tiene un ledger de puntos ciegos:

  1. Trate el ledger como una entrada, no como una verdad. Vuelva a verificar los hallazgos de alto impacto o desactualizados contra el código/documentos actuales.
  2. Clasifique la salida como nuevo, cambiado, confirmado, downgradeado, resuelto o necesita-decisión.
  3. No repita elementos pendientes sin cambios a menos que bloqueen el objetivo actual. Esto es lo que hace que las ejecuciones repetidas se sientan como progreso en lugar de molestia.
  4. Si el ledger es nuevo pero no está enrutado desde un índice, traspaso o README de operaciones, márquelo como un punto ciego de descubrimiento.
  5. Preserve el idioma de estado local del ledger y los ID al actualizarlo.

Los buenos ledgers hacen que las auditorías futuras sean más baratas. Los malos ledgers se convierten en otro documento oculto, así que siempre verifique la capacidad de descubrimiento.

Higiene de Búsqueda

Use búsquedas acotadas. Las auditorías de puntos ciegos a menudo tocan repositorios amplios, y los archivos generados ruidosos pueden crear falsa confianza o desperdiciar contexto.

Exclusiones predeterminadas para rg y herramientas similares a menos que la auditoría apunte explícitamente a esas áreas:

!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**

Prefiera rutas específicas y exclusiones --glob sobre escaneos de todo el repositorio. Si un escaneo amplio devuelve archivos generados enormes, deténgase y vuelva a ejecutar con un límite más ajustado antes de usar el resultado.

Flujo de Trabajo

1. Definir el Mapa

Indique el objetivo aparente del usuario, tipo de proyecto, madurez y su límite de auditoría en 2-4 líneas. Marque las suposiciones explícitamente. Incluya un perfil del propietario:

  • ¿Solo o en equipo? ¿En qué es claramente experto el propietario y - más útil - en qué NO es experto? Los puntos ciegos se agrupan en las áreas no expertas del propietario, así que pondere esos lentes hacia arriba.
  • ¿Pasatiempo o comercial? ¿Privado o público? La intención comercial o pública activa lentes legales, fiscales y de mercado que serían puro ruido para un proyecto de pasatiempo privado. Si la intención no se puede leer de los archivos, pregunte antes de escanear (una pregunta corta) - adivinar mal la intención desperdicia toda la auditoría.

2. Reunir Evidencia

Use el ayudante de inventario más lecturas específicas. Lea primero las superficies de autoconciencia del proyecto (README, TODO, hoja de ruta, listas de verificación, documentos de diseño, sinopsis/esquema) - son tanto su mejor fuente de perfil como su filtro de ruido (Regla Básica 1). Prefiera evidencia sobre especulación amplia. Etiquete la evidencia como:

  • observada: directamente presente en archivos o salidas.
  • ausente: artefacto esperado no encontrado en el alcance inspeccionado.
  • inferida: probable de la estructura, nombres o convenciones.
  • pregunta: requiere confirmación del usuario o propietario del dominio.

3. Clasificar el Territorio

Elija uno o más arquetipos de references/archetypes.md. No fuerce el proyecto en una categoría si es híbrido.

4. Ejecutar Lentes

Aplique solo los lentes que se ajusten a la etapa del proyecto. Un prototipo no necesita cumplimiento empresarial, pero aún puede necesitar límites de pérdida de datos, manejo de secretos o recuperabilidad.

5. Escaneo Externo de Ojos Frescos

Cuando el anfitrión tenga acceso web, haga investigación con límite de tiempo sobre dos preguntas:

  1. ¿Qué tratan los proyectos saludables de esta categoría como equipo estándar ahora mismo?
  2. ¿Qué cambió en los últimos 6-12 meses (regulación, política de plataforma, convenciones de mercado o género, herramientas) que los documentos de este proyecto no podrían contener?

La pregunta 2 es desproporcionadamente valiosa: los cambios dependientes del tiempo son estructuralmente invisibles tanto para el repositorio como para la memoria del propietario. (Dato de campo: en las primeras ejecuciones, los hallazgos de mayor impacto individual (una ley de etiquetado de contenido de IA que entraba en vigencia el próximo mes, una adquisición de proveedor de pagos que invalidaba un plan documentado) provinieron todos de este paso). Cite fuentes para cualquier cosa encontrada aquí. Sin acceso web, omita y divulgue (consulte Política de Superficie del Anfitrión).

6. Convertir Puntos Ciegos en Verificaciones

Para cada hallazgo, incluya:

  • qué puede estar faltando.
  • por qué es importante para este proyecto.
  • evidencia.
  • siguiente verificación más económica.
  • probable propietario o superficie de decisión.
  • prioridad: ahora, siguiente, después o vigilancia.
  • confianza: alta, media, baja.

Descarte candidatos que aparezcan en los documentos de seguimiento del proyecto (Regla Básica 1), mantenga los 3-7 principales y mueva el resto a la lista de vigilancia o ledger.

7. Entrevistar al Propietario

Presente los hallazgos, luego pregunte cuáles el propietario ya conocía (una sola pregunta de selección múltiple funciona bien en anfitriones capaces de elegir). Clasifique cada hallazgo:

ConcienciaSignificadoPrescripción
desconocido_desconocidoEl propietario no sabíaExplique por qué es importante aquí + primer paso más económico
desconocido_conocidoEl propietario sabía, pero no está escrito en ningún ladoLa solución es documentación, no implementación - póngalo en sus documentos de seguimiento para que los agentes y futuras sesiones puedan verlo
salto_deliberadoEl propietario lo consideró y eligió no hacerloMuévalo a la lista de salto CON la razón y un desencadenante de re-verificación

(Dato de campo: en las primeras ejecuciones, aproximadamente la mitad de los hallazgos principales resultaron ser desconocido_conocido - brechas reales en el repositorio, pero no en la cabeza del propietario. La distinción cambia por completo el seguimiento).

En anfitriones que no pueden preguntar, marque cada valor de conciencia como no confirmado, incruste las preguntas de la entrevista en el informe y ponga las decisiones abiertas en un Paquete de decisión.

8. Mantener la Salida Útil

Lidere con los puntos ciegos de mayor señal. Siempre incluya las dos secciones de confianza (Regla Básica 4). Escriba el informe y la prosa del ledger en el idioma que el propietario está usando en la conversación; mantenga los ID, estado y valores de conciencia en inglés para que las re-ejecuciones sigan siendo diferenciales entre sesiones e idiomas. Formatee según references/report-template.md.

Barreras de Seguridad

  • No presente las mejores prácticas genéricas como hallazgos a menos que la evidencia del proyecto las haga relevantes.
  • No vuelva a reportar elementos que ya existen en el ledger o los documentos de seguimiento del proyecto.
  • No requiera proceso pesado para experimentos personales o prototipos tempranos.
  • No haga cambios de código a menos que el usuario pida explícitamente remediación.
  • No reclame que algo está roto solo porque un archivo está ausente; diga lo que sugiere la ausencia y cómo confirmar.
  • Trate la ausencia de CI, pruebas, documentos de lanzamiento o archivos de despliegue solo como un punto ciego cuando el proyecto reclame entrega repetible, traspaso compartido o fiabilidad similar a producción. Las notas personales y prototipos tempranos pueden no necesitarlos.
  • No entierre al usuario en cada riesgo posible. Clasifique por adecuación al proyecto, radio de explosión, reversibilidad y probabilidad.
  • Cuando el usuario no sea experto en el dominio, incluya notas de enseñanza cortas para puntos ciegos desconocidos.
  • Cuando un hallazgo dependa del comportamiento actual de la plataforma externa, verifique con documentos oficiales o investigación actual antes de tratarlo como hecho; sin acceso web, preséntelo como no verificado.
  • No omita los hallazgos de alta gravedad solo porque son incómodos. Póngalos claramente, pero sin alarma, y siempre con el primer paso más económico. El objetivo es calma informada, no pánico. La calma informada es lo que permite al propietario priorizar; el pánico produce parálisis o decisiones apresuradas.

Estructura de Archivos

blindspot-audit/
├── SKILL.md
├── scripts/
│   └── project_inventory.py
├── templates/
│   └── BLINDSPOT_LEDGER.md
└── references/
    ├── archetypes.md
    ├── host-surfaces.md
    ├── ledger-lifecycle.md
    ├── lenses.md
    └── report-template.md

Integración con Otros Skills

Las salidas de Blindspot Audit (ledger de puntos ciegos + informe) son entradas naturales para los siguientes tipos de skills:

  • Planificación y Documentación: un ledger actualizado le dice a un skill de planificación dónde enfocar las preguntas de diseño en lugar de adivinar.
  • Onboarding: los nuevos contribuyentes pueden leer el ledger para encontrar decisiones abiertas, supuestos no verificados y riesgos conocidos antes de sumergirse en el código.
  • Post-mortems: un ledger con hallazgos de post-implementación captura decisiones que aún no se han tomado, lo cual es más útil que las lecciones aprendidas una vez que ya es demasiado tarde.
  • Seguridad y Cumplimiento: los hallazgos marcados como sensibles al tiempo o dependientes de regulación son banderas para skills de seguridad antes de que se conviertan en incidentes.
  • Priorización de Hoja de Ruta: los puntos ciegos de alta gravedad con el propietario y el siguiente paso ya identificados ahorran a los gerentes de producto una ronda de investigación.

La integración es simplemente: el skill de consumo lee BLINDSPOT_LEDGER.md en la raíz del proyecto o la ubicación documentada. No se requiere ningún protocolo especial - el ledger es un archivo de marcado plano con una estructura de tabla predecible.

Skills relacionados