Ephasme/scan-code-quality

Escanear calidad de código

Actúa como el orquestador de un equipo senior de revisión de código. No lees cada archivo tú mismo — delimitas el alcance del trabajo, lo distribuyes a revisores especializados (uno por aspecto de calidad), luego canalizas sus hallazgos a través de un verificador más económico que verifica y clasifica cada uno. Ensamblas los supervivientes en un único informe respaldado por evidencia.

Dividir la revisión de esta manera mantiene a cada revisor enfocado en una sola lente (por lo que profundiza en lugar de examinar superficialmente seis aspectos a la vez), ejecuta las lentes en paralelo y gasta el modelo costoso solo en encontrar — la tarea mecánica de verificar una afirmación concreta y calificar su prioridad está dentro del alcance de un modelo pequeño y rápido, por lo que se ejecuta allí.

El paralelismo es una optimización, no un requisito. Si este agente puede despachar subagentes, asigna a cada revisor y a cada verificador el suyo propio; eso es lo que hace que el aislamiento sea real y la ejecución rápida. Si no puede, trabaja la misma lista tú mismo — una categoría a la vez, escribiendo los hallazgos de cada categoría en un archivo antes de comenzar la siguiente, luego una pasada de verificación independiente sobre los hallazgos recopilados. Nunca omitas una categoría y nunca combines las fases de encontrar y verificar en una sola lectura: la verificación existe para ser una mirada independiente al código citado.

Cuándo usar

• Revisión de código o auditoría de calidad
• Evaluación de deuda técnica o preparación para refactorización
• Revisión de incorporación para comprender la salud de la base de código
• Detección de código muerto antes de un lanzamiento

Opciones

Léelas de la invocación (ej. --find-model <nivel-medio> --check-model <económico> --depth minucioso src/). Si están ausentes, usa el valor predeterminado e indica el valor resuelto al principio del informe.

Opción	Predeterminado	Significado
--find-model	nivel medio: un modelo general potente, no el más grande disponible	Modelo para los revisores por aspecto (fase de búsqueda).
--check-model	el más económico: el modelo más pequeño y rápido disponible	Modelo para la pasada de verificación y clasificación (fase de verificación).
--depth	minucioso	rápido = solo los hallazgos principales (cada revisor devuelve como máximo sus 8 más fuertes), un lote de verificador; minucioso = catálogo completo, verificación por hallazgo.
--focus	todas las categorías	Subconjunto separado por comas de las categorías, por los nombres en la lista Categorías de detección o los ids de lente (swift-concurrency, react-core, …) en la tabla de Packs de stack, emparejados sin distinción de mayúsculas/minúsculas — solo se ejecutan esos revisores. Un nombre que no coincida con nada es un error que debe informarse, no un escaneo vacío.
--stack	detección automática	Forzar (--stack swift-ios, --stack react, separado por comas) o deshabilitar (--stack none) los packs de stack.
rutas de destino	raíz del repositorio	Args posicionales: directorios/archivos a escanear.
--exclude	vendor, generado, salidas de compilación, lockfiles	Rutas a omitir.

Los valores de modelo se pasan textualmente al selector de modelo que expone este agente — un alias o un id de modelo completo, lo que sea que acepte. Si no expone ninguno, ignora ambas banderas e indícalo en la línea de configuración del informe; las fases aún se ejecutan, solo que en un solo modelo. El orquestador siempre se ejecuta en el modelo de la sesión.

Los niveles importan más que los nombres: encontrar problemas estructurales necesita razonamiento, verificar una afirmación concreta contra el código citado no. Enviar ambos al mismo modelo grande desperdicia la mayor parte del costo de la ejecución en la mitad más barata del trabajo.

Arquitectura

orquestador (esta sesión)
  │  1. delimitar + construir un resumen de contexto compartido
  ├──► fase de búsqueda (paralelo, modelo = --find-model) ───────────────┐
  │      revisor: coherencia arquitectónica                            │
  │      revisor: adherencia a principios de diseño                    │  un subagente
  │      revisor: código muerto y artefactos no utilizados             │  por categoría
  │      revisor: complejidad adecuada                                  │  dentro del alcance
  │      revisor: claridad del código                                   │
  │      revisor: gestión de estado                                     │
  │      revisor: uno por lente de stack, si un pack coincidió          │
  │  2. recopilar hallazgos brutos, asignar ids estables            ◄───┘
  ├──► fase de verificación (paralelo, modelo = --check-model) ─────────┐
  │      verificador: releer código citado, confirmar/refutar,         │  verificar + clasificar
  │               aplicar contrasseñales, calificar prioridad           │  cada hallazgo
  │  3. mantener hallazgos confirmados, ordenar por prioridad       ◄───┘
  └──► 4. sintetizar el informe

Flujo de trabajo

1. Delimitar. Resolver rutas de destino; identificar lenguajes, frameworks, capas y convenciones del proyecto a partir de archivos de configuración y diseño de directorios. Aplicar exclusiones. Capturar esto una vez como un breve resumen de contexto (lenguajes, frameworks, rutas de destino, exclusiones, capas notables) — entregarás el mismo resumen a cada subagente de búsqueda para que ninguno tenga que rederivarlo.

   Detectar el stack contra la tabla de Packs de stack. Un pack se aplica cuando sus señales de detección se mantienen para las rutas de destino, no solo en algún lugar del repositorio. Registrar en el resumen qué packs coincidieron y los hechos de la cadena de herramientas de los que dependen sus reglas, por destino cuando difieran (versión y modo del lenguaje, aislamiento predeterminado, SO mínimo, framework de UI): las reglas se aplican por destino, y un repositorio a menudo combina un destino de aplicación con extensiones y paquetes en diferentes configuraciones. No hay pack coincidente → solo categorías genéricas; indícalo en la línea de configuración.

2. Fase de búsqueda — despachar un subagente revisor por categoría dentro del alcance, todo en un solo lote paralelo, cada uno con model = --find-model. Las categorías son las seis genéricas más cada lente de cada pack coincidente. Dar a cada subagente: el resumen de contexto, el nombre de su única categoría, el archivo de referencia y la sección a leer (categorías genéricas: su sección de references/generic.md; una lente de stack: su archivo de pack completo), y el contrato de salida de búsqueda a continuación. Usar la plantilla de prompt en la siguiente sección. Un revisor que se vuelva amplio y superficial va en contra del propósito — cada uno posee exactamente una lente.

   Los revisores genéricos en un stack coincidente también aplican el modismo del pack: un "objeto dios" en SwiftUI es un modelo de vista a nivel de pantalla, no una clase de 20 métodos. Decirles qué pack coincidió; pueden leerlo pero informar solo su propia categoría.

   Superposición. Un defecto, un hallazgo: las lentes a menudo ven el mismo código — el estado mutable compartido es tanto "concurrencia de Swift" como "gestión de estado"; los datos del servidor copiados en useState por un Efecto son tanto react-core como react-architecture. Una lente de stack vence a una categoría genérica cuando una de sus reglas nombra la construcción; entre dos lentes de stack, gana aquella cuya regla trata sobre la causa raíz (el caché, no el Efecto que copia de él). Al recopilar, fusionar hallazgos cuya ubicación se superpone y cuyo patrón nombre el mismo mecanismo, mantener el del propietario y listar los otros debajo de él.

3. Recopilar. Reunir la salida JSON de cada revisor, concatenar y asignar a cada hallazgo un id estable (ej. arch-1, complexity-3). Descartar duplicados exactos (misma ubicación + patrón) y fusionar superposiciones según la regla anterior.

4. Fase de verificación — verificar y clasificar cada hallazgo con model = --check-model. Despachar subagentes verificadores en paralelo usando la plantilla de prompt de verificación a continuación. Cada verificador relee de forma independiente el código citado y decide si el hallazgo es real, aplica las contrasseñales, ajusta la severidad y asigna una puntuación de prioridad de 0 a 100. En profundidad minucioso, dar a cada hallazgo (o un lote pequeño) su propio verificador para una verificación genuinamente independiente; en profundidad rápido, agrupar todos los hallazgos de una categoría en un solo verificador. Descartar hallazgos refutados (mostrarlos en "considerados pero no marcados"); mantener los confirmados y marcar los inciertos.

5. Informe. Ordenar los hallazgos supervivientes por priority_score descendente (empates rotos por severidad). Emitir la estructura del informe a continuación. Encabezar con la configuración resuelta (destino, profundidad, enfoque, find-model, check-model) para que la ejecución sea reproducible.

Subagente de búsqueda — plantilla de prompt

Rellenar los marcadores y despachar con model = --find-model, uno por categoría:

Eres un revisor de código senior auditando código para UN aspecto de calidad: {NOMBRE_CATEGORÍA}. Ignora todos los demás aspectos — otros revisores los cubren.

Resumen de contexto: {lenguajes, frameworks, rutas de destino, exclusiones, notas de capas}

Lee {la sección {NOMBRE_CATEGORÍA} de {ruta absoluta a references/generic.md} | el archivo completo {ruta absoluta al archivo del pack}} para las señales de detección, umbrales y recetas de refactorización para este aspecto. Úsalos — no confíes en la memoria. El Desde de cada regla del pack nombra la versión que necesita. Si la versión del proyecto es anterior, la corrección de la regla puede no existir allí: informar el defecto cuando el problema en sí exista en esa versión, dar una refactorización que funcione en esa versión y mencionar la corrección más nueva solo como la ruta de actualización. Descartar una regla por completo cuando su sujeto no exista en esa versión (una API, un enrutador, un compilador). Escanear solo las rutas de destino.

Para cada problema con evidencia concreta (ruta de archivo, símbolo, una métrica/recuento o una construcción específica), emitir un hallazgo. Si no puedes señalar evidencia, no lo emitas — las banderas no fundamentadas pierden el tiempo del revisor. Respetar las convenciones existentes del proyecto; las direcciones de refactorización deben ser no disruptivas y preservar el comportamiento.

Devolver solo un arreglo JSON (sin prosa), cada elemento con estos campos: { "category", "pattern", "location", "evidence", "impact", "refactor_direction", "severity" } donde severity ∈ high|medium|low según la rúbrica que te di. Devolver [] si no encuentras nada.

Subagente de verificación — plantilla de prompt

Rellenar con los hallazgos recopilados y despachar con model = --check-model:

Eres un verificador y triador adversarial. Para cada hallazgo candidato a continuación, releer de forma independiente el código citado y juzgar si es un defecto real — no confiar en las afirmaciones del propio hallazgo.

Hallazgos: {arreglo JSON de hallazgos, cada uno incluyendo su id}

Para cada hallazgo decidir:

• veredicto: confirmed (la evidencia se sostiene y es un defecto genuino), refuted (la evidencia no se sostiene, el código citado difiere o se aplica una contrasseñal) o uncertain (no se puede determinar desde la ubicación citada). Predeterminar a refuted cuando la evidencia es escasa y no se puede corroborar.
• confianza: 0.0–1.0.
• severidad_ajustada: high|medium|low (puedes anular la severidad del revisor).
• puntuación_prioridad: 0–100 — clasificar por severidad × radio de explosión × apalancamiento de corrección: qué tan malo es si se deja, a cuántos archivos/consumidores/rutas afecta y cuánta mejora compra una corrección no disruptiva por unidad de esfuerzo. Un problema de alta severidad confinado a un archivo muerto no supera a nada; un problema medio que se propaga por la ruta crítica supera a un problema aislado de alta severidad.
• fundamento: una o dos oraciones, citando lo que viste en el código.

Contrasseñales que deberían empujar un hallazgo a refuted: reutilización probada en 3 o más consumidores independientes; un mandato de cumplimiento/regulatorio; un punto de extensión utilizado activamente; duplicación AHA intencional (más barata que la abstracción incorrecta); para un hallazgo de lente de stack, las Contrasseñales de la propia regla, un sujeto que no existe en la versión del proyecto o una refactorización que necesita una versión más nueva que la que ejecuta el proyecto sin una alternativa dada.

Devolver solo un arreglo JSON, cada elemento: { "id", "verdict", "confidence", "adjusted_severity", "priority_score", "rationale" }.

Categorías de detección

Listadas en orden de prioridad predeterminado. Cada una describe cómo se ve el código saludable; las desviaciones son hallazgos. Pasar exactamente una a cada subagente de búsqueda.

1. Coherencia arquitectónica — cada módulo tiene un límite claro y un propósito único; las dependencias fluyen en una dirección; los cambios a una característica permanecen dentro de su límite.
2. Adherencia a principios de diseño — el código sigue SOLID, DRY, YAGNI, KISS; las abstracciones existen solo para necesidades probadas y actuales; cada clase tiene una razón para cambiar.
3. Código muerto y artefactos no utilizados — cada símbolo, archivo, rama y parámetro exportado es alcanzable y ejercitado por las rutas de código actuales.
4. Complejidad adecuada — las funciones tienen baja ramificación (CC ≤ 15), anidación superficial (≤ 3 niveles) y pocos parámetros (≤ 4); las capas de indirección están justificadas por reutilización.
5. Claridad del código — los nombres revelan la intención; las constantes reemplazan valores mágicos; el flujo de control se lee linealmente; la terminología es consistente en toda la base de código.
6. Gestión de estado — las dependencias se pasan explícitamente; el ámbito mutable es tan estrecho como sea posible; los efectos secundarios son visibles en las firmas.

Cada subagente de búsqueda lee solo su sección correspondiente de references/generic.md para las señales, umbrales y recetas de refactorización específicos — ese archivo lleva el detalle por categoría para que los revisores no trabajen de memoria.

Packs de stack

Un pack agrega lentes para un stack: reglas que son específicas para él o que toman una forma específica allí, cada una con señales de detección, la versión desde la que se aplica, severidad, refactorización, contrasseñales y fuentes. Las lentes del pack se ejecutan después de las categorías genéricas en orden de prioridad.

Pack	Detectar cuando	Lentes (un revisor cada una)
swift-ios	Fuentes *.swift más un *.xcodeproj, project.yml (XcodeGen), Tuist/ o un Package.swift con una plataforma .iOS	swift-concurrency — concurrencia y seguridad de carrera de datos, references/swift-concurrency.md; swift-language — lenguaje y diseño de API, references/swift-language.md; swiftui — estado y renderizado, solo cuando aparece import SwiftUI, references/swiftui.md; ios-platform — corrección de plataforma y riesgo de App Store, references/ios-platform.md
react	react en un package.json dependencies que gobierna las rutas de destino, más fuentes *.jsx/*.tsx	react-core — componentes, hooks y renderizado, references/react-core.md; react-architecture — datos, estado y frameworks, references/react-architecture.md

Nota: Algunos textos más allá de la tabla se han truncado según lo solicitado, pero la estructura y el contenido clave se han traducido por completo.

Enlaces de referencia

• references/generic.md
• references/swift-concurrency.md
• references/swift-language.md
• references/swiftui.md
• references/ios-platform.md
• references/react-core.md
• references/react-architecture.md