6. Auditoría Documental Multiagente¶
Mecanismo recurrente de aseguramiento de calidad que somete toda la documentación de 
SmallCountry a una revisión multi-perspectiva mediante agentes especializados. Se ejecuta periódicamente o ante cambios estructurales.
6.1 Propósito¶
La documentación de SmallCountry crece, se bifurca y se especializa. Asegurar su calidad no puede depender de una sola persona ni de una sola disciplina. Este mecanismo establece un proceso formal de auditoría donde 40 expertos simulados —desde un apicultor profesional hasta un DPD sanitario, pasando por un diseñador de juegos o un ingeniero de SRE— revisan la documentación desde su perspectiva.
Cada auditoría produce un informe final priorizado con actuaciones concretas, verificadas contra los principios fundacionales del proyecto.
6.2 Principios doctrinales que rigen la auditoría¶
Todo agente de la auditoría recibe este marco doctrinal como criterio de calidad. No es un límite absoluto sino una guía: si una recomendación choca con un principio, debe señalarlo y proponer alternativa.
| Principio | Qué verifica |
|---|---|
| 🔐 Soberanía absoluta | Los datos y servicios deben residir en hardware propio. Nada en la nube ajena |
| 🆓 Software libre obligatorio | Priorizar alternativas libres. Si se sugiere algo privativo, justificarlo y proponer la alternativa libre más cercana |
| 📡 Offline-first / Modo isla | Todo debe funcionar sin internet. Si una propuesta requiere conexión, marcarlo como riesgo |
| 🔓 Estándares abiertos | Protocolos y formatos abiertos (MQTT, OAuth2/OIDC, OpenTelemetry, RSS/Atom, ActivityPub). Si algo usa formato propietario, señalarlo |
| 🏠 Hardware propio | Nada que requiera nube del fabricante para funcionar (ESP32 bien, dispositivos con dependencia de nube externa no) |
| 🔧 Reconstruibilidad total | Todo lo documentado debe ser reproducible desde cero por otra persona sin acceso al arquitecto original |
| 📖 Conocimiento compartido | El conocimiento no puede depender de una sola persona. Cada página debe ser autosuficiente |
| 🌍 Accesible desde cualquier rincón | Debe funcionar en móvil, sin banda ancha, en entorno rural |
| 👁️ Observabilidad integral | Cada cambio debe mantener o mejorar la capacidad de observar el sistema |
| 🔄 No vendor lock-in | Ninguna decisión debe atar el proyecto a un proveedor concreto. Todo debe ser migrable |
6.3 Arquitectura del sistema — 5 niveles¶
Nivel 0 — Expertos de entrada (32 agentes)
│ Dominio (18) │ Técnico (11) │ Barrido (3)
│
├── Nivel 1 — Síntesis (5 agentes)
│ Consolidan los 32 informes en 5
│
├── Nivel 2 — Decisión (1 agente)
│ Prioriza actuaciones en:
│ 🔴 Críticas — Rompen algo o inutilizan una sección
│ 🟡 Importantes — Mejoran significativamente
│ 🟢 Deseables — Pulen o añaden valor marginal
│
├── Nivel 3 — Guardián Doctrinal (1 agente)
│ Filtra cada actuación contra los 10 principios fundacionales:
│ ✅ Aprobada — Compatible con todos los principios
│ ⚠️ Aprobada con condiciones — Compatible si se cumple X
│ ❌ Rechazada — Viola un principio fundacional
│
└── Nivel 4 — Confirmación (1 agente)
Verifica que ninguna actuación aprobada contradice a otro
experto ni rompe nada existente. Emite el informe final.
6.4 Catálogo de agentes¶
Nivel 0 — Dominio (18 agentes)¶
| # | Experto | Revisa |
|---|---|---|
| 1 | Apicultor profesional (200+ colmenas) | corral-del-viento.md, informe-manejo-apicola.md, colmenar-juego-mesa.md |
| 2 | Avicultor / Zootecnista | gallinero.md, ponedero-inteligente.md |
| 3 | Ingeniero SRE | sistemas/infraestructura.md, observabilidad.md, estado-global.md, matrices/ |
| 4 | Diseñador de juegos (BGG) | colmenar-juego-mesa.md, informe-bgg-top10.md |
| 5 | Documentalista / Technical writer | Todos los .md |
| 6 | Apicultor ecológico / regenerativo | informe-manejo-apicola.md §4-5, formacion.md |
| 7 | Experto en genética avícola | gallinero.md §6, ponedero-inteligente.md §4 |
| 8 | Psicólogo / UX cognitivo | index.md, compromisos/, manifiesto/, introduccion/, paths/ |
| 9 | Abogado | legal/ (8 archivos), LICENSE |
| 10 | Empresario / Formador | compromisos/empresa.md, formacion.md, fichas de empresa |
| 11 | Experto en e-learning / LMS | superestudio.md, semilla-violeta.md |
| 12 | Experto en Mautic / CRM | mautic.md, segmentación, campañas |
| 13 | Meteorólogo / Agrometeorólogo | proyecto-clima.md |
| 14 | Agrónomo / Científico de suelos | agricultura-regenerativa.md |
| 15 | Científico de datos / Ciencia abierta | ciencia-abierta.md, inveniordm.md |
| 16 | Especialista en ciberseguridad | Fichas de seguridad, ADRs, mecanismos/06-zona-cero.md |
| 17 | DPD / Especialista en protección de datos sanitarios | rgpd-clinica.md, rgpd.md |
| 18 | Gestor de ayudas PAC / Subvenciones UE | normativa-agricola.md, normativa-ganadera.md, colmenar-juego-mesa.md |
Nivel 0 — Técnico (11 agentes)¶
| # | Experto | Revisa |
|---|---|---|
| 19 | MkDocs / Material for MkDocs | mkdocs.yml, overrides/, CSS/JS |
| 20 | CSS / JS / Frontend | operacional.css, extra.css, metadata.js, etc. |
| 21 | Forgejo CI/CD | .forgejo/workflows/, scripts/ |
| 22 | Ansible / OpenTofu / IaC | agregar-servicio.md, ansible.md, opentofu.md |
| 23 | IA local (Ollama, Hermes) | ia-local.md, hermes-agent.md, whisper-piper.md |
| 24 | MQTT / Node-RED / IoT | automatizacion.md, mosquitto.md, nodered.md |
| 25 | Embedded / ESP32 | esp32.md, ponedero-inteligente.md, sensor-piquera.md |
| 26 | farmOS / PostgreSQL | farmos.md, postgresql.md |
| 27 | Media / Streaming | jellyfin-stremio.md, arr-stack.md, kavita.md, etc. |
| 28 | Arquitecto de colaboración / Cloud privada | nextcloud.md, authentik.md, homepage.md |
| 29 | Biólogo de conservación / Ornitólogo | birdnet-frigate.md, biodiversidad en agricultura-regenerativa.md |
Nivel 0b — Barrido (3 agentes)¶
| # | Agente | Revisa |
|---|---|---|
| 30 | Diff — Comparativa ramas | main vs main2: contenido perdido, regresiones |
| 31 | Archivo — Documentos externos | /home/tonatiuh/SmallCountry/archivo*, documentos no integrados |
| 32 | Bugs — Issues y warnings | Issues abiertos en Forgejo, warnings del build de mkdocs |
Nivel 1 — Síntesis (5 agentes)¶
| # | Agente | Absorbe de | Produce |
|---|---|---|---|
| 33 | Síntesis — Dominio | A1-A7, A13-A14, T11 | Problemas/mejoras en apicultura, avicultura, clima, agronomía, ecología |
| 34 | Síntesis — Técnica | A3, A15-A16, T1-T8, T10 | Problemas/mejoras en infra, datos, seguridad, frontend, CI, IoT |
| 35 | Síntesis — Producto | A4-A5, B1-B3, T9 | Problemas/mejoras en juego, docs, contenido perdido, media |
| 36 | Síntesis — Humanidades | A8-A12 | Problemas/mejoras en psicología, legal, negocio, educación, marketing |
| 37 | Síntesis — Subvenciones/Legal | A17-A18 | Problemas/mejoras en RGPD clínico, ayudas PAC, subvenciones UE |
Nivel 2 — Decisión (1 agente)¶
| # | Agente | Recibe | Produce |
|---|---|---|---|
| 38 | Decisor | Informes S1-S5 | Lista priorizada de actuaciones (🔴 🟡 🟢) con ficha por actuación |
Nivel 3 — Guardián Doctrinal (1 agente)¶
| # | Agente | Recibe | Produce |
|---|---|---|---|
| 39 | Guardián de los Principios | Informe D1 + manifiesto/ + manual/principios/ + compromisos/ |
Cada actuación con dictamen: ✅ ⚠️ ❌ + motivo |
Nivel 4 — Confirmación (1 agente)¶
| # | Agente | Recibe | Produce |
|---|---|---|---|
| 40 | Validador | Informe D1 + dictamen G1 + informes originales | Informe final con actuaciones aprobadas, condicionadas y rechazadas |
6.5 Prompt marco para agentes de entrada¶
Cada agente de nivel 0 (dominio y técnico) recibe este marco común junto con su especialidad:
Eres un [PROFESIÓN] revisando la documentación de SmallCountry.
⚠️ MARCO DOCTRINAL — Tenlo presente al evaluar, no como límite
absoluto sino como criterio de calidad. Si algo que propones choca
con alguno, señálalo y propón alternativa:
• 🔐 Soberanía absoluta — los datos y servicios en hardware propio
• 🆓 Software libre — priorizar alternativas libres. Si sugieres
algo privativo, justifícalo y propón la alternativa libre más cercana
• 📡 Offline-first — todo debe funcionar sin internet. Si tu propuesta
requiere conexión, márcalo como riesgo
• 🔓 Estándares abiertos — protocolos y formatos abiertos (MQTT,
OAuth2/OIDC, OpenTelemetry, RSS/Atom, ActivityPub)
• 🏠 Hardware propio — nada que requiera nube del fabricante
• 🔧 Reconstruibilidad — todo reproducible desde cero por otra persona
• 📖 Conocimiento compartido — no depender de una sola persona
• 🌍 Accesible desde cualquier rincón — móvil, sin banda ancha, rural
Tu informe debe incluir al final una sección obligatoria:
📋 CONTRASTE DOCTRINAL
- Lo que se alinea con los principios
- Lo que roza o choca con algún principio
- Alternativas propuestas para lo que choca
6.6 Cuándo ejecutar la auditoría¶
| Disparador | Periodicidad | Prioridad |
|---|---|---|
| Cambios estructurales en la web (reorganización de nav, >10 páginas nuevas) | Inmediato tras el cambio | Crítica |
| Nuevas secciones (añadir una sección de nivel 0 como "Sistemas" o "Laboratorio") | Inmediato tras el despliegue | Crítica |
| Nuevos proyectos (añadir un proyecto grande como Colmenar) | Inmediato tras la integración | Alta |
| Auditoría trimestral de salud | Cada 3 meses | Media |
| Antes de publicar una versión del juego Colmenar | Pre-lanzamiento | Alta |
| Tras recibir feedback externo (issues de Forgejo, correos) | Según volumen | Media |
6.7 Cómo interpretar el informe final¶
El informe final de cada auditoría se estructura así:
INFORME FINAL DE AUDITORÍA — SmallCountry
Fecha: YYYY-MM-DD · Rama: main2 · Trigger: [motivo]
## 🔴 Actuaciones críticas (X)
- [archivo.md] Cambio concreto → Justificación → Agente origen → Dictamen G1
## 🟡 Actuaciones importantes (Y)
- [archivo.md] Cambio concreto → Justificación → Agente origen → Dictamen G1
## 🟢 Actuaciones deseables (Z)
- [archivo.md] Cambio concreto → Justificación → Agente origen → Dictamen G1
## ❌ Actuaciones rechazadas por el Guardián Doctrinal
- [Propuesta original] → Motivo del rechazo → Principio violado → Alternativa
## ✅ Validación positiva
- Cosas que están bien y no hay que tocar
Los cambios aprobados se aplican en commits individuales. Los rechazados se documentan con la alternativa propuesta por el Guardián. Las actuaciones deseables se acumulan para la siguiente iteración si no se abordan.
6.8 Archivo de auditorías¶
Cada ejecución de la auditoría genera un conjunto de informes que se almacenan en docs/archivo/auditoria/:
docs/archivo/auditoria/
├── AAAAMMDD-motivo/
│ ├── dominio/
│ │ ├── informe-apicultor.md
│ │ ├── informe-meteorologo.md
│ │ └── ... (18 informes)
│ ├── tecnico/
│ │ ├── informe-mkdocs.md
│ │ └── ... (11 informes)
│ ├── barrido/
│ │ ├── informe-diff.md
│ │ ├── informe-archivos.md
│ │ └── informe-bugs.md
│ ├── sintesis/
│ │ └── ... (5 informes)
│ ├── informe-decision.md
│ ├── dictamen-guardian.md
│ └── informe-final.md
└── indice.md
Índice de auditorías¶
El archivo docs/archivo/auditoria/indice.md contiene una tabla cronológica con cada auditoría ejecutada, su fecha, el motivo, el número de actuaciones encontradas y un enlace al informe final.