ZeroQ Knowledge Map

Cómo funciona esta estructura

Esta knowledge base está organizada en secciones numeradas que cubren todo el ciclo de vida de la documentación técnica de ZeroQ:

Reglas obligatorias

1. Feature no documentada = feature no terminada. Ningún feature se considera completo hasta que su documentación esté creada y aprobada.
2. Cambio sin update de documentación = cambio no aprobado. Todo PR que modifique comportamiento debe incluir actualización de la doc correspondiente.
3. Un servicio = un archivo. No se fragmenta la documentación de un servicio en múltiples archivos.
4. No se duplica información. Las relaciones se declaran en metadatos (related_services, depends_on), no copiando texto.
5. No se documenta en Slack. Si es importante, va en esta knowledge base.
6. Toda integración tiene su propio archivo en 01-Architecture/Integrations/.
7. Todo cliente con entorno dedicado tiene su subcarpeta en 05-Clients/.

Convenciones de nombrado

Ver detalle completo en [[Naming-Conventions]].

Esquema de metadatos

Todos los documentos deben comenzar con frontmatter YAML. Ver esquema completo en [[Metadata-Schema]].

---
type: service | feature | infra | integration | policy | procedure | rfp | module
status: draft | approved | deprecated
owner: 
review_cycle: quarterly | annual
criticality: low | medium | high | mission-critical
environment: prod | staging | shared | dedicated
deploy_target: kubernetes | docker | lambda | static    # solo type: service
framework:                                               # solo type: service
framework_version:                                       # solo type: service
runtime:                                                 # solo type: service
runtime_version:                                         # solo type: service
related_services: []
depends_on: []
exposes_api: true | false
uses_database: []
uses_queue: []
uses_cache: []
compliance_tags: []
client_specific: true | false
last_reviewed: YYYY-MM-DD
---

Cómo usar los templates

Los templates están en 07-Templates/. Para crear un nuevo documento:

1. Copiar el template correspondiente al tipo de documento.
2. Renombrar con el prefijo correcto (ej: SVC-MiServicio.md).
3. Mover a la carpeta correspondiente.
4. Completar el frontmatter con los valores reales.
5. Rellenar las secciones.

Templates disponibles:

• [[TEMPLATE-Service]] → para documentar servicios
• [[TEMPLATE-Feature]] → para documentar features
• [[TEMPLATE-Integration]] → para documentar integraciones

Cómo los agentes AI deben usar los metadatos

Los agentes AI pueden consumir esta knowledge base de forma estructurada:

1. Grafo de dependencias: Recorrer depends_on y related_services para construir el mapa completo de relaciones entre componentes.
2. Detección de docs desactualizadas: Comparar last_reviewed con review_cycle para alertar sobre documentos vencidos.
3. Respuestas a licitaciones: Filtrar por type: rfp y compliance_tags para encontrar respuestas reutilizables.
4. Análisis de impacto: Dado un servicio, recorrer recursivamente depends_on y related_services para determinar el blast radius de un cambio.
5. Identificación de riesgos: Cruzar criticality: mission-critical con status: draft para encontrar componentes críticos sin documentación aprobada.

Queries Dataview útiles

Listar todos los servicios mission-critical

TABLE status, owner, last_reviewed
FROM "01-Architecture/Services"
WHERE type = "service" AND criticality = "mission-critical"
SORT last_reviewed ASC

Documentos pendientes de revisión

TABLE type, owner, last_reviewed, review_cycle
FROM ""
WHERE status = "approved" AND last_reviewed < date(today) - dur(90 days)
SORT last_reviewed ASC

Features por módulo

TABLE status, criticality, owner
FROM "02-Product/Features"
WHERE type = "feature"
SORT file.name ASC

Integraciones activas

TABLE status, criticality, environment, client_specific
FROM "01-Architecture/Integrations"
WHERE type = "integration" AND status != "deprecated"
SORT criticality DESC

Documentos en estado draft

TABLE type, owner, criticality
FROM ""
WHERE status = "draft"
SORT criticality DESC

Cómo mantener consistencia

1. Revisiones periódicas: Cada documento tiene un review_cycle. Usar la query Dataview de arriba para identificar documentos vencidos.
2. Ownership claro: Todo documento tiene un owner. Si el owner cambia de equipo, reasignar.
3. PR reviews: Incluir verificación de documentación en el checklist de code review.
4. Onboarding: Todo nuevo miembro del equipo debe leer 00-Governance/ antes de contribuir.
5. No documentar en otro lado: Si la información es relevante, vive aquí. No en Confluence, no en Notion, no en Slack.