system-audit

name	system-audit
version	1.0.0
description	Procedimiento sistemático para auditar repositorios de sistemas de software — analizar arquitectura, identificar fortalezas, detectar problemas y proponer mejoras con criterios objetivos.
tags	["audit","architecture","code-review","quality-assessment","multi-agent"]

System Audit — Auditoría Sistemática de Repositorios

Resumen

Procedimiento para auditar un repositorio o sistema de software completo: explorar la estructura, leer archivos clave, identificar fortalezas y debilidades, y proponer mejoras priorizadas.

Cuándo usar

• Usuario pide "auditoría", "review", "qué te parece", "qué mejorarías" de un repositorio o sistema
• Evaluación de calidad antes de integrar un sistema nuevo
• Revisión de un proyecto propio para detectar deuda técnica
• Análisis de un framework o patrón encontrado en otro repo

Flujo de Auditoría (5 pasos)

Paso 1: Exploración de estructura

# Árbol de archivos
find . -maxdepth 2 -type f -o -type d | sort
# Conteo de archivos
find . -name "*.md" | wc -l
# Log reciente
git log --oneline -20
# Remote y branch
git remote -v
git branch -a

Objetivo: Entender la escala del proyecto, su historia reciente, y su superficie de código.

Paso 2: Lectura de archivos clave (prioridad)

Leer SIEMPRE estos archivos en orden:

1. README → Qué es el proyecto, cómo funciona, badges, estructura
2. Archivo de entrada principal (AGENTS.md, README.md, index.html, main.py, etc.)
3. Configuración del sistema (config.yaml, _system-config.md, .env.example)
4. Documentación de arquitectura (ARCHITECTURE.md, docs/)
5. Workflow/CI (.github/workflows/)
6. Índices de conocimiento (skills index, learnings index, clusters)
7. Agentes/roles principales (los que definen el comportamiento central)
8. Plantillas (templates que otros siguen)
9. Estado actual (session state, TODOs pendientes, tareas sin cerrar)

Paso 3: Análisis de fortalezas

Evaluar cada dimensión con criterio (MÍNIMO 8 dimensiones):

Dimensión	Qué buscar
Arquitectura	Separación de responsabilidades, patrones de diseño, capas
Memoria/conocimiento	Cómo se almacena, filtra, recupera y deprecia el conocimiento
Orquestación	Cómo se coordinan los componentes, flujos adaptativos
Calidad	Revisión, criticado, validación, tests
Documentación	README, arquitectura, templates, contribución
Portabilidad	Rutas absolutas, dependencias de SO, configuración portable
UX/Comunicación	Checkpoints, formatos de output, protocolos de delegación
Auto-mejora	Aprendizaje acumulado, reaprendizaje, métricas
Tokens y costes	Tracking de tokens, costes por sesión, optimización de contexto
Seguridad	Secrets en repo, .gitignore correcto, credenciales hardcodeadas
Deploy/CI/CD	Workflows funcionales, branches limpios, CI configurado
Integración móvil	Telegram, accesibilidad desde móvil, canales de comunicación

Regla: Nunca evaluar menos de 8 dimensiones. Las dimensiones de tokens/costes, seguridad y deploy son OBLIGATORIAS en auditorías de sistemas multi-agente.

Paso 4: Detección de problemas (categorías)

Clasificar cada problema encontrado en una de estas categorías:

Categoría	Severidad	Ejemplos
🔴 Crítico	Rompe el sistema o la portabilidad	Rutas absolutas hardcodeadas, estado corrupto, datos perdidos
🟡 Importante	Limita la utilidad o escalabilidad	Sin métricas, mecanismo de auto-mejora sin usar, criterios subjetivos
🟢 Menor	Mejora la calidad pero no bloquea	Branch naming, falta de CHANGELOG, CSS duplicado

Paso 5: Propuestas de mejora priorizadas

Para cada problema, proponer una mejora concreta:

• Prioridad Alta → Afecta portabilidad, funcionalidad o escalabilidad
• Prioridad Media → Mejora la utilidad, mantenibilidad o coherencia
• Prioridad Baja → Buenas prácticas, consistencia, documentación

Patrones comunes que debes detectar

Patrones de arquitectura bien diseñados

• Dos capas (documental + ejecutable) sin duplicación
• Índice inteligente con carga bajo demanda
• Flujo adaptativo basado en complejidad
• Agente de mantenimiento autónomo (bibliotecario/archiver)
• Protocolos de comunicación estructurados

Patrones de arquitectura problemáticos

• Rutas absolutas hardcodeadas en config
• Mecanismos de auto-mejora sin datos que los alimenten
• Criterios subjetivos donde deberían ser objetivos
• Estado de sesión sin limpieza (tareas "pendientes" que nunca se archivan)
• CSS/estilos duplicados entre componentes
• Verificador de instalación que solo funciona en un SO

Patrones de memoria/conocimiento

• Índice con señales de relevancia + decay (bueno)
• Learnings individuales cargados siempre (malo — gasta tokens)
• Skills sin "ciclo de reaprendizaje" cuando el mecanismo existe
• Clusters dinámicos vs. estáticos

Patrones de criticado — activación objetiva

• Señal de alerta: El Critic se activa por "dudas" subjetivas del orchestrator
• Patrón correcto: 6 criterios objetivos: complejidad ≥4, ≥3 reintentos, ≥3 archivos, impacto alto, reviewer emite WARNINGs, solicitud humana explícita
• Señal de éxito: El orchestrator evalúa los criterios automáticamente sin preguntar

Formato de output

Presentar la auditoría en este formato:

# 🔍 Auditoría Completa — [Nombre del Sistema]

## 📊 Panorama General
| Dimensión | Estado |
|-----------|--------|
| ... | ... |

## ✅ Lo que está MUY BIEN
### 1. [Nombre del aspecto positivo]
[Explicación de POR QUÉ es bueno, no solo QUÉ es bueno]

## ⚠️ Problemas detectados
### 🔴 Críticos
[Problema] → [Por qué es crítico]

### 🟡 Importantes
[Problema] → [Por qué es importante]

### 🟢 Menores
[Problema] → [Por qué es menor]

## 💡 Mejoras que propondría
### Prioridad Alta
[A] [Mejora] → [Impacto esperado]

### Prioridad Media
[B] [Mejora] → [Impacto esperado]

### Prioridad Baja
[C] [Mejora] → [Impacto esperado]

## 📈 Veredicto global
**Puntuación: X/10**

[Resumen de 2-3 líneas con tu opinión honesta sobre el sistema]

Post-Audit Execution Pipeline

Cuando el usuario autoriza ejecutar las mejoras propuestas en la auditoría:

Paso 1: Priorizar por severidad

Prioridad	Categoría	Acción
P0	🔴 Crítico	Ejecutar inmediatamente (rompe funcionalidad)
P1	🟡 Importante	Ejecutar en orden de impacto
P2	🟢 Menor	Ejecutar al final o batch

Paso 2: Plan de cambios

Antes de ejecutar, presentar plan concreto:

# Para cada problema P0:
- Archivo: path/al/archivo.xyz
- Cambio: descripción exacta del cambio
- Líneas: ~20 afectadas
- Riesgo: bajo/medio/alto

# Para P1-P2, agrupar por dominio (docs, infra, código)

Regla: NO ejecutar sin presentar plan y obtener ✅ del usuario en cambios >3 archivos.

Paso 3: Ejecución

• P0 individuales → directo (terminator, patch)
• P0 paralelos independientes → delegate_task en paralelo
• P1-P2 relacionados → agrupar en un delegate_task con todas las instrucciones
• Documentación → Mastermind directo (no requiere delegación)
• CI/Deploy → revisar primero, luego ejecutar

Paso 4: Verificación

Por cada grupo de cambios ejecutado:

1. git diff --stat para confirmar archivos tocados
2. Esanear referencias residuales con search_files
3. git commit con mensaje en castellano y descriptivo
4. git push

Paso 5: Medir delta

Al final de la ejecución:

- Pre-auditoría: 5.6/10
+ Post-ejecución: ~7.5/10
+ Delta: +1.9 puntos

Incluir el delta en el resumen final para que el usuario vea el progreso tangible.

Alternativa: Pipeline de Crons Secuenciales

Cuando el usuario no puede estar presente para supervisar la ejecución en vivo (o las mejoras son muchas y deben ejecutarse una por una):

1. Crear crons once escalonados (15-20 min de separación), cada uno autocontenido
2. Cada cron hace UNA mejora concreta: lee archivos → ejecuta cambio → verifica → commit → resumen
3. Todos con deliver: origin para que el usuario vea el progreso en tiempo real
4. Último cron = REVISIÓN FINAL: verifica checklist completo, y si algo falla → crea cron de reparación
5. Independientes: si uno falla, el siguiente igual funciona (no hay dependencias entre ellos)
6. Idempotentes: re-ejecutar uno no rompe nada

Formato del prompt de cada cron:

Eres Mastermind. TAREA: [descripción concreta]
PASOS:
1. [leer/verificar]
2. [ejecutar cambio]
3. [verificar cambio]
4. [commit + push]
RESUMEN: [qué cambió antes→después]

Patrón probado: 14 crons secuenciales para ejecutar mejoras de auditoría, divididos en dos fases:

• Fase 1 (8 crons): Infraestructura y limpieza — README real, Mastermind disclaimer, ChromaDB auto-start, ChromaDB re-index, SOUL.md integration, skill dedup, skill priority consolidation, crons pausados eliminados
• Fase 2 (6 crons): Inteligencia — memoria decay (Ebbinghaus), knowledge graph, skill lifecycle, delegation flows, dashboard HTML, revisión final
• Cada cron es autocontenido (lee → ejecuta → verifica → commit → resumen) e idempotente (re-ejecutar no rompe nada)
• El cron de revisión final verifica checklist completo y crea un cron de mantenimiento semanal que re-ejecuta todo los domingos
• Fase 2 depende de Fase 1 — los crons de inteligencia usan scripts/paths creados en Fase 1. Separar en fases evita que un fallo en infra destruya features de inteligencia

Post-Migration Cleanup Execution

Cuando una migración de plataforma/paradigma ya se completó (v3.1→v4.0, de Obsidian→GitHub, etc.), a menudo quedan referencias residuales en los archivos activos. El ejecutable de limpieza sigue este flujo:

Paso 1: Escaneo sistemático de referencias legacy

Usar search_files con los nombres de la plataforma antigua para encontrar TODAS las referencias en archivos activos (excluyendo legacy/ y .git/):

patterns = ['obsidian', 'opencode', 'ebbinghaus', 'wikilink', '[[', 'slash command']
for root, dirs, files in os.walk(base):
    # excluir .git, legacy/, learning-platform/
    for fname in files:
        if fname.endswith(('.md', '.json', '.html', '.yml', '.sh', '.bat', '.js')):
            # buscar cada patrón, reportar línea exacta

Paso 2: Clasificar cada referencia

Tipo	Acción	Ejemplo
Contexto de migración (CHANGELOG, tablas comparativas)	✅ Mantener	"v3.1 usaba OpenCode + Obsidian"
Instrucciones activas (CONTRIBUTING, guías de inicio)	🔄 Reescribir	"Abrir como vault de Obsidian"
Landing page desactualizada	🔄 Reescribir	index.html con 11 agentes, Ebbinghaus
Scripts de verificación obsoletos	🔄 Actualizar o 🗑️ eliminar	verify-system.bat que chequea .opencode/
Documentación en otro idioma desactualizada	🔄 Simplificar o 🗑️ eliminar	README_EN.md que v3.1
READMEs y docs que comparan versiones	✅ Mantener	Las comparativas dan contexto

Paso 3: Ejecutar cambios por archivo

Para cada archivo que necesita cambios:

• Landing page: Reescribir entera (cambia el mensaje, el branding, los KPIs)
• CONTRIBUTING: Reescribir entero (las instrucciones de instalación cambian completamente)
• CHANGELOG: Traducir/actualizar manteniendo el historial
• Scripts de sistema: Actualizar estructura de verificación al nuevo layout
• Workflows CI: Actualizar excludes de paths que ya no existen

Paso 4: Verificación final

Re-escanear para confirmar que no quedan referencias activas:

grep -rl "obsidian\|opencode\|ebbinghaus" --include="*.md" --include="*.html" . | grep -v legacy/ | grep -v .git/

Luego: git add -A && git commit con mensaje descriptivo + push.

Ver references/post-migration-cleanup.md para el caso real de limpieza del Mastermind v3.1→v4.0.

Adjunto: Auditoría de apps Node.js multi-usuario (Express + SQLite)

Cuando el proyecto auditado es una aplicación web Node.js con Express, SQLite (sql.js) y autenticación multiusuario, añadir estas dimensiones específicas al flujo de 5 pasos:

Dimensiones adicionales obligatorias

Dimensión	Qué buscar	Patrón problema	Referencia
Helpers SQL	¿sql_run, sql_all, sql_get existen? ¿Se usan correctamente?	sql_run() para SELECT → datos perdidos silenciosamente	Patrón 1
Aislamiento multi-tenant	¿Los datos de cada usuario están aislados por usuario_id?	getMeta('nombre') global en vez de usuarios.nombre	Patrón 2
Auth	Token en header vs cookie. ¿Limpieza de sesiones expiradas?	Token en URL (logs), sin cleanup periódico	Patrón 3
Onboarding	¿Formulario fijo o conversacional? ¿Se adapta al usuario?	Pasos fijos sin IA, sin personalidad de coach	Patrón 4
Persistencia de chat	¿Mensajes de IA en servidor o solo localStorage?	Chat perdido al cambiar navegador/dispositivo	Patrón 5

Cómo leer la referencia

El archivo references/nodejs-multiuser-audit-patterns.md contiene 5 patrones detallados con:

• Síntoma (cómo lo detecta un usuario)
• Causa (qué código lo produce)
• Detección automática (comandos grep/curl)
• Verificación funcional (cómo confirmar el bug)
• Lección (cómo prevenirlo en el futuro)

Checklist rápido para auditoría Node.js multi-usuario

# 1. Verificar helpers SQL
grep -n "function sql_run\|function sql_all\|function sql_get" server.js

# 2. Buscar sql_run usado para SELECT (antipattern)
grep -n "sql_run.*SELECT" server.js

# 3. Buscar getMeta() en funciones perfilUsuario
grep -n "getMeta" server.js | grep -i "nombre\|perfil\|user"

# 4. Verificar auth: limpieza de sesiones
grep -n "DELETE FROM sesiones" server.js

# 5. Verificar si chat tiene persistencia en servidor
grep -n "chat\|mensaje\|conversacion" server.js

# 6. Verificar aislamiento multi-tenant en todas las queries
grep -n "usuario_id" server.js | head -20

# 7. Verificar onboarding
grep -n "onboarding\|onboard" server.js

Adjunto: Auditoría de Frontend SPA — Data-Trace Audit

Cuando el proyecto es un frontend SPA (HTML autocontenido, React, Vue, etc.) que carga datos de archivos JSON/GeoJSON/CSV, añadir esta dimensión específica:

Técnica: Data-Trace Audit

El problema clásico: el repo acumula datos que el frontend nunca carga (PDFs, GeoJSONs, lookup tables, scripts de fix completados). Resultado: repos de 300+ MB cuando el frontend solo necesita 10 MB de JSONs.

Flujo: