workspace-v1/orchestration/analisis/ANALISIS-ESTANDARES-DOCUMENTACION-WORKSPACE-2026-01-10.md

ANALISIS CONSOLIDADO - ESTANDARES DE DOCUMENTACION WORKSPACE

Fecha: 2026-01-10 Fase: 1 - Analisis Detallado Estado: COMPLETADO Version: 1.0.0

---

1. RESUMEN EJECUTIVO

1.1 Proyectos Analizados

Proyecto	Archivos MD	Lineas	Estructura	Madurez
gamilit	1,434	243,061	Fases EAI/EXT + orchestration	ALTA
erp-core	881	~180,000	Modulos MGN + orchestration	ALTA
michangarrito	93	~15,000	Epicas MCH + orchestration	MEDIA
template-saas	34	8,364	Modulos SAAS + ADR	MEDIA

1.2 Patrones Comunes Identificados

1. Numeracion por Fases: 00-09 (vision), 01-0N (fases), 90-99 (transversal)
2. Archivos Indice: _MAP.md en cada nivel
3. Prefijos por Tipo: RF-, ET-, US-, ADR-, SAAS-, MCH-, MGN-
4. Metadata Estructurada: YAML frontmatter o tablas Markdown
5. Orchestration Separado: Cada proyecto tiene /orchestration/
6. Inventarios YAML: MASTER_INVENTORY, DATABASE_INVENTORY, etc.

---

2. PATRONES DE NOMENCLATURA CONSOLIDADOS

2.1 Nomenclatura de Archivos

Tipo	Patron	Ejemplos
Requerimientos	RF-{MODULO}-{NUM}.md	RF-AUTH-001.md, RF-CATALOG-002.md
Especificaciones	ET-{TIPO}-{MODULO}.md	ET-BACKEND-MGN-001.md, ET-AUTH-backend.md
User Stories	US-{EPICA}-{NUM}-{desc}.md	US-FUND-001-autenticacion.md
Epicas (gamilit)	EAI-{NUM}-{nombre}/	EAI-001-fundamentos/, EXT-005-reportes/
Modulos (erp)	MGN-{NUM}-{nombre}/	MGN-001-auth/, MGN-010-financial/
Epicas (mich)	MCH-{NUM}-{nombre}.md	MCH-001-infraestructura-base.md
Modulos (saas)	SAAS-{NUM}-{nombre}.md	SAAS-001-auth.md, SAAS-014-whatsapp.md
ADRs	ADR-{NUM}-{descripcion}.md	ADR-0001-monorepo.md
Planes	PLAN-{DESC}-{FECHA}.md	PLAN-CONSOLIDACION-BD-2026-01-07.md
Analisis	ANALISIS-{DESC}-{FECHA}.md	ANALISIS-ERRORES-ADMIN-2026-01-07.md
Validaciones	VALIDACION-{DESC}-{FECHA}.md	VALIDACION-PLAN-ADMIN-2026-01-07.md
Reportes	REPORTE-{DESC}-{FECHA}.md	REPORTE-EJECUCION-SPRINT1-2026-01-07.md
Trazas	TRAZA-{TIPO}-{DESC}.md	TRAZA-TAREAS-BACKEND.md
Indices	_MAP.md	docs/_MAP.md, orchestration/_MAP.md
Inventarios	{TIPO}_INVENTORY.yml	MASTER_INVENTORY.yml

2.2 Nomenclatura de Directorios

Nivel	Patron	Ejemplos
Fase numerada	{NN}-{nombre-kebab}/	00-vision-general/, 01-fase-alcance/
Transversal	90-{nombre}/	90-transversal/, 95-guias-desarrollo/
Quick ref	96-{nombre}/	96-quick-reference/
ADRs	97-adr/	Siempre 97
Finiquito	99-{nombre}/	99-finiquito/, 99-troubleshooting/

---

3. ESTRUCTURA DE DOCUMENTOS ESTANDAR

3.1 Frontmatter YAML (Requerido)

---
id: "{PREFIJO}-{MODULO}-{NUM}"
title: "{Titulo descriptivo}"
type: "{Requirement|Specification|UserStory|ADR|Epic}"
status: "{Done|InProgress|Backlog|Documented}"
priority: "{P0|P1|P2|P3|Alta|Media|Baja}"
module: "{modulo_afectado}"
epic: "{EPICA-ID}"
version: "{SEMVER}"
labels: ["{tag1}", "{tag2}"]
created_date: "{YYYY-MM-DD}"
updated_date: "{YYYY-MM-DD}"
---

3.2 Estructura de Contenido MD

# {ID}: {Titulo}

## Metadata (tabla alternativa si no hay frontmatter)
| Campo | Valor |
|-------|-------|
| ID | {ID} |
| Prioridad | {P0-P3} |
| Estado | {Estado} |

---

## Descripcion
{Parrafo introductorio}

## Objetivos / Alcance
1. {Objetivo 1}
2. {Objetivo 2}

## Contenido Principal
{Seccion especifica por tipo de documento}

## Dependencias / Referencias
- Link a documento relacionado
- Link a documento relacionado

---

**Ultima actualizacion:** {YYYY-MM-DD}
**Version:** {SEMVER}

3.3 Estructura de _MAP.md (Indice)

# _MAP: {Nombre Seccion}

**Carpeta:** {ruta/relativa}/
**Proposito:** {Descripcion}
**Estado:** {Actualizado|En construccion}
**Ultima actualizacion:** {YYYY-MM-DD}

---

## Resumen
| Metrica | Valor |
|---------|-------|
| Total archivos | X |
| Story Points | X |
| Estado | X% |

## Contenido

| Archivo | Tipo | Estado | Descripcion |
|---------|------|--------|-------------|
| {archivo.md} | {tipo} | {estado} | {descripcion} |

## Navegacion por Caso de Uso

### Para {caso X}:
1. {paso 1}
2. {paso 2}

## Referencias
- [Link a seccion](../ruta/archivo.md)

---

4. CATEGORIAS DE DOCUMENTACION

4.1 Matriz de Categorias por Proyecto

Categoria	gamilit	erp-core	michangarrito	template-saas
Vision/Estrategia	00-vision-general/	00-vision-general/	00-vision-general/	00-vision-general/
Fases/Epicas	01-03-fase-*/	01-03-fase-*/	01-epicas/	01-modulos/
Requerimientos	*/requerimientos/	03-requerimientos/	(en epicas)	(en modulos)
Especificaciones	*/especificaciones/	04-modelado/	02-especificaciones/	02-especificaciones/
User Stories	*/historias-usuario/	05-user-stories/	(en epicas)	-
ADRs	97-adr/	97-adr/	-	architecture/adr/
Transversal	90-transversal/	90-transversal/	90-transversal/	-
Guias	95-guias-desarrollo/	-	-	02-devops/
Quick Reference	96-quick-reference/	-	-	-
Integraciones	-	-	-	02-integraciones/
Orchestration	orchestration/	orchestration/	orchestration/	orchestration/

4.2 Contenido Minimo por Categoria

Vision/Estrategia:

• VISION-*.md - Proposito y objetivos
• README.md - Indice de seccion
• ARQUITECTURA-*.md - Stack y decisiones

Fases/Epicas:

• README.md - Descripcion de fase
• TIMELINE.yml - Cronograma (si aplica)
• _MAP.md - Indice de contenido
• Subcarpetas por epica

Requerimientos (RF):

• Frontmatter con ID, prioridad, estado
• Descripcion del negocio
• Criterios de aceptacion
• Reglas de negocio (RN-*)

Especificaciones (ET):

• Referencia a RF asociado
• Arquitectura/Modelo de datos
• Endpoints API (si aplica)
• Implementacion tecnica

User Stories (US):

• Formato: Como X, Quiero Y, Para Z
• Criterios de aceptacion (BDD)
• Tareas tecnicas desglosadas
• Definition of Done

ADRs:

• Contexto del problema
• Opciones consideradas
• Decision y justificacion
• Consecuencias

---

5. SISTEMA DE ORCHESTRATION

5.1 Estructura Estandar

orchestration/
├── 00-guidelines/
│   ├── CONTEXTO-PROYECTO.md
│   └── HERENCIA-SIMCO.md (o HERENCIA-DIRECTIVAS.md)
├── analisis/
│   ├── ANALISIS-*.md
│   ├── PLAN-*.md
│   └── VALIDACION-*.md
├── inventarios/
│   ├── MASTER_INVENTORY.yml
│   ├── DATABASE_INVENTORY.yml
│   ├── BACKEND_INVENTORY.yml
│   └── FRONTEND_INVENTORY.yml
├── reportes/
│   └── REPORTE-*.md
├── trazas/
│   ├── TRAZA-TAREAS-DATABASE.md
│   ├── TRAZA-TAREAS-BACKEND.md
│   └── TRAZA-TAREAS-FRONTEND.md
├── CONTEXT-MAP.yml
├── PROJECT-STATUS.md
├── PROXIMA-ACCION.md
└── README.md

5.2 Archivos Obligatorios por Proyecto

Archivo	Proposito	Obligatorio
CONTEXT-MAP.yml	Mapeo de contexto y aliases	SI
PROJECT-STATUS.md	Estado actual del proyecto	SI
PROXIMA-ACCION.md	Siguiente paso a ejecutar	RECOMENDADO
MASTER_INVENTORY.yml	Inventario consolidado	SI
HERENCIA-SIMCO.md	Herencia de directivas	SI

---

6. INVENTARIOS Y SSOT

6.1 Estructura de MASTER_INVENTORY.yml

metadata:
  proyecto: "{nombre}"
  version: "{SEMVER}"
  updated: "{YYYY-MM-DD}"
  tipo: "{Standalone|Suite|Vertical}"

resumen:
  progreso_mvp: "{N}%"
  story_points_completados: {N}
  story_points_totales: {N}

fases:
  - nombre: "Fase 1"
    estado: "{completado|en_progreso|pendiente}"
    progreso: "{N}%"

aplicaciones:
  backend:
    - servicio: "{nombre}"
      puerto: {N}
      estado: "{activo|inactivo}"
  frontend:
    - servicio: "{nombre}"
      puerto: {N}
      estado: "{activo|inactivo}"

schemas:
  - nombre: "{schema}"
    tablas: {N}

modulos:
  - nombre: "{modulo}"
    estado: "{implementado|documentado|pendiente}"

6.2 Estructura de DATABASE_INVENTORY.yml

version: "{SEMVER}"
updated: "{YYYY-MM-DD}"

schemas:
  - nombre: "{schema_name}"
    descripcion: "{descripcion}"
    tablas:
      - nombre: "{tabla}"
        columnas: {N}
        indices: {N}
        estado: "{implementada|pendiente}"
    funciones:
      - nombre: "{funcion}"
        tipo: "{trigger|function|procedure}"
    triggers:
      - nombre: "{trigger}"
        tabla: "{tabla_asociada}"

---

7. GAPS IDENTIFICADOS EN ESTANDARIZACION

7.1 Gaps a Nivel de Workspace

Gap	Descripcion	Impacto	Prioridad
Testing minimo	No hay estandar de cobertura minima	ALTO	P0
Logging	Falta formato estandar de logs	MEDIO	P1
Error handling	Estructura de errores no uniforme	MEDIO	P1
API versioning	No especificado en directivas	MEDIO	P1
Migraciones BD	Sin protocolo estandarizado	ALTO	P0
Rollback	Procedimientos no formalizados	MEDIO	P1
Rate limiting	Mencionado pero sin directiva	BAJO	P2
Caching	Sin directiva operativa	BAJO	P2
Monitoreo	Poco integrado con SIMCO	MEDIO	P1

7.2 Gaps por Proyecto

gamilit:

• Documentacion muy madura, pocos gaps
• Podria estandarizar mas los reportes de sprint

erp-core:

• Trazabilidad excelente
• Falta integracion con sistema de testing

michangarrito:

• Estructura clara pero menos detallada que gamilit
• Falta inventario de integraciones externas

template-saas:

• Buena estructura base
• Algunos archivos de orchestration en _archivo/ (legacy)

---

8. ESTANDARES PROPUESTOS

8.1 Directivas Nuevas Requeridas

Directiva	Proposito	Prioridad
SIMCO-TESTING.md	Estandar minimo de testing	P0
SIMCO-LOGGING.md	Formato y niveles de logs	P1
SIMCO-ERROR-HANDLING.md	Estructura uniforme de errores	P1
SIMCO-MIGRACIONES-BD.md	Protocolo de migraciones	P0
SIMCO-API-VERSIONING.md	Estrategia de versionado	P1
SIMCO-ROLLBACK.md	Procedimientos de rollback	P1
SIMCO-INTEGRACIONES.md	Estandar para APIs externas	P1

8.2 Templates Nuevos Requeridos

Template	Proposito
TEMPLATE-EPICA-ESTANDAR.md	Estructura uniforme de epicas
TEMPLATE-MODULO-ESTANDAR.md	Estructura uniforme de modulos
TEMPLATE-INTEGRACION-EXTERNA.md	Documentar integraciones
TEMPLATE-INVENTARIO-PROYECTO.md	Estructura de inventarios
TEMPLATE-REPORTE-SPRINT.md	Reportes de sprint uniformes

8.3 Checklists Nuevos

Checklist	Proposito
CHECKLIST-DOCUMENTACION-PROYECTO.md	Validar estructura docs
CHECKLIST-INVENTARIOS.md	Validar inventarios YAML
CHECKLIST-ESTANDARES-NOMENCLATURA.md	Validar nombres

---

9. MATRIZ DE MADUREZ DE DOCUMENTACION

Escala de Madurez (1-5)

Nivel	Descripcion
1	Sin estructura, documentacion ad-hoc
2	Estructura basica, nomenclatura inconsistente
3	Estructura definida, faltan algunos elementos
4	Estructura completa, trazabilidad parcial
5	Estructura completa, trazabilidad total, SSOT

Evaluacion por Proyecto

Proyecto	Estructura	Nomenclatura	Trazabilidad	SSOT	Total
gamilit	5	5	5	5	5.0
erp-core	5	5	5	4	4.75
michangarrito	4	4	3	4	3.75
template-saas	4	4	3	3	3.5

---

10. PROXIMOS PASOS

Fase 2: Planeacion

1. Crear directivas faltantes (7 nuevas)
2. Crear templates nuevos (5 nuevos)
3. Crear checklists (3 nuevos)
4. Definir orden de implementacion

Fase 3: Validacion

1. Validar directivas contra proyectos existentes
2. Verificar compatibilidad con SIMCO existente
3. Revisar dependencias entre directivas

Fase 4: Dependencias

1. Mapear impacto en cada proyecto
2. Identificar archivos a modificar
3. Planificar propagacion

Fase 5: Refinamiento

1. Ajustar segun validaciones
2. Priorizar por impacto

Fase 6: Ejecucion

1. Crear directivas
2. Crear templates
3. Actualizar indices

Fase 7: Validacion Final

1. Verificar integracion
2. Probar en proyecto piloto
3. Documentar resultado

---

Documento generado: 2026-01-10 Siguiente fase: PLANEACION