workspace-v1/orchestration/analisis/PLAN-ESTANDARIZACION-DOCUMENTACION-WORKSPACE-2026-01-10.md

PLAN DE ESTANDARIZACION - DOCUMENTACION WORKSPACE

Fecha: 2026-01-10 Fase: 2 - Planeacion Estado: EN_PROGRESO Version: 1.0.0 Referencia: ANALISIS-ESTANDARES-DOCUMENTACION-WORKSPACE-2026-01-10.md

---

1. OBJETIVO DEL PLAN

Crear y documentar estandares, directivas y lineamientos para la documentacion de proyectos en el workspace, basados en los patrones identificados en:

• gamilit (madurez 5.0)
• erp-core (madurez 4.75)
• michangarrito (madurez 3.75)
• template-saas (madurez 3.5)

---

2. SEGMENTACION DE TAREAS

2.1 BLOQUE A: Directivas SIMCO Nuevas (7 directivas)

ID	Directiva	Prioridad	Dependencias	Tokens Est.
A1	SIMCO-DOCUMENTACION-PROYECTO.md	P0	Ninguna	~800
A2	SIMCO-NOMENCLATURA.md	P0	A1	~600
A3	SIMCO-ESTRUCTURA-DOCS.md	P0	A1, A2	~700
A4	SIMCO-INVENTARIOS.md	P1	A1	~500
A5	SIMCO-TESTING.md	P0	Ninguna	~600
A6	SIMCO-MIGRACIONES-BD.md	P0	SIMCO-DDL	~500
A7	SIMCO-INTEGRACIONES-EXTERNAS.md	P1	Ninguna	~500

2.2 BLOQUE B: Templates Nuevos (5 templates)

ID	Template	Prioridad	Dependencias	Tokens Est.
B1	TEMPLATE-EPICA-ESTANDAR.md	P0	A3	~400
B2	TEMPLATE-MODULO-ESTANDAR.md	P0	A3	~400
B3	TEMPLATE-MAP-INDICE.md	P0	A2	~300
B4	TEMPLATE-INVENTARIO-PROYECTO.md	P1	A4	~350
B5	TEMPLATE-INTEGRACION-EXTERNA.md	P1	A7	~300

2.3 BLOQUE C: Checklists (3 checklists)

ID	Checklist	Prioridad	Dependencias	Tokens Est.
C1	CHECKLIST-DOCUMENTACION-PROYECTO.md	P0	A1, A2, A3	~400
C2	CHECKLIST-INVENTARIOS.md	P1	A4	~300
C3	CHECKLIST-NOMENCLATURA.md	P0	A2	~300

2.4 BLOQUE D: Actualizacion de Indices y Referencias

ID	Archivo	Accion	Prioridad
D1	INDICE-DIRECTIVAS-WORKSPACE.yml	Agregar nuevas directivas	P0
D2	orchestration/directivas/simco/_MAP.md	Actualizar indice	P0
D3	orchestration/templates/_MAP.md	Actualizar indice	P0
D4	orchestration/checklists/_MAP.md	Crear/Actualizar	P0
D5	shared/knowledge-base/standards/	Agregar estandares	P1

2.5 BLOQUE E: Integracion en Proyectos

ID	Proyecto	Accion	Prioridad
E1	gamilit	Validar conformidad, ajustar si necesario	P2
E2	erp-core	Validar conformidad, ajustar si necesario	P2
E3	michangarrito	Aplicar estandares faltantes	P1
E4	template-saas	Aplicar estandares faltantes	P1

---

3. DETALLE DE TAREAS POR BLOQUE

3.1 BLOQUE A: Directivas SIMCO

A1: SIMCO-DOCUMENTACION-PROYECTO.md

Objetivo: Establecer el estandar base para documentacion de proyectos

Contenido:

1. Proposito y alcance
2. Principios fundamentales de documentacion
3. Estructura obligatoria de /docs
4. Estructura obligatoria de /orchestration
5. Archivos minimos requeridos
6. Ciclo de vida de documentos
7. Validaciones requeridas

Secciones obligatorias:

• Estructura de directorios
• Archivos minimos
• Convenciones de actualizacion
• Referencias cruzadas

A2: SIMCO-NOMENCLATURA.md

Objetivo: Estandarizar nomenclatura de archivos y directorios

Contenido:

1. Principios de nomenclatura
2. Patrones por tipo de archivo:
   - Requerimientos (RF-*)
   - Especificaciones (ET-*)
   - User Stories (US-*)
   - Epicas (EAI-*, EXT-*, MCH-*, MGN-*)
   - Modulos (SAAS-*)
   - ADRs (ADR-*)
   - Planes (PLAN-*)
   - Analisis (ANALISIS-*)
   - Reportes (REPORTE-*)
   - Trazas (TRAZA-*)
   - Inventarios (*_INVENTORY.yml)
   - Indices (_MAP.md)
3. Patrones de directorios:
   - Numeracion de fases (00-99)
   - Kebab-case para nombres
4. Casos especiales
5. Anti-patrones a evitar

A3: SIMCO-ESTRUCTURA-DOCS.md

Objetivo: Definir estructura interna de documentos

Contenido:

1. Frontmatter YAML obligatorio
2. Estructura de contenido por tipo:
   - Requerimientos
   - Especificaciones
   - User Stories
   - Epicas/Modulos
   - ADRs
   - _MAP.md (indices)
3. Secciones obligatorias vs opcionales
4. Formato de tablas
5. Diagramas ASCII
6. Referencias cruzadas
7. Footer de documentos

A4: SIMCO-INVENTARIOS.md

Objetivo: Estandarizar inventarios YAML

Contenido:

1. Proposito de inventarios
2. Tipos de inventarios:
   - MASTER_INVENTORY.yml
   - DATABASE_INVENTORY.yml
   - BACKEND_INVENTORY.yml
   - FRONTEND_INVENTORY.yml
3. Estructura YAML por tipo
4. Campos obligatorios
5. Actualizacion y mantenimiento
6. Validacion de inventarios

A5: SIMCO-TESTING.md

Objetivo: Establecer estandares minimos de testing

Contenido:

1. Principios de testing
2. Cobertura minima por tipo:
   - Backend: 70% unit, 50% integration
   - Frontend: 60% components
   - Database: 100% migrations
3. Tipos de tests requeridos:
   - Unit tests
   - Integration tests
   - E2E tests (si aplica)
4. Nomenclatura de archivos de test
5. Estructura de carpetas de test
6. Comandos de ejecucion
7. Integracion con CI/CD

A6: SIMCO-MIGRACIONES-BD.md

Objetivo: Protocolo de migraciones de base de datos

Contenido:

1. Principios de migraciones
2. Nomenclatura de archivos:
   - {TIMESTAMP}-{descripcion}.sql
3. Estructura de migracion
4. Rollback obligatorio
5. Testing de migraciones
6. Documentacion requerida
7. Flujo de aprobacion
8. Integracion con SIMCO-DDL

A7: SIMCO-INTEGRACIONES-EXTERNAS.md

Objetivo: Estandar para documentar APIs externas

Contenido:

1. Cuando usar esta directiva
2. Estructura de documentacion:
   - Proveedor y proposito
   - Credenciales requeridas
   - Endpoints utilizados
   - Rate limits
   - Manejo de errores
   - Fallbacks
3. Multi-tenant considerations
4. Variables de entorno
5. Testing de integraciones

---

3.2 BLOQUE B: Templates

B1: TEMPLATE-EPICA-ESTANDAR.md

# {ID}: {Nombre Epica}

## Metadata
- **Codigo:** {ID}
- **Fase:** {N} - {Nombre Fase}
- **Prioridad:** {P0|P1|P2|P3}
- **Estado:** {Completado|En Proceso|Pendiente|Documentado}
- **Fecha inicio:** {YYYY-MM-DD}
- **Fecha fin estimada:** {YYYY-MM-DD}
- **Story Points:** {N}

## Descripcion
{Parrafo descriptivo del proposito de la epica}

## Objetivos
1. {Objetivo 1}
2. {Objetivo 2}
3. {Objetivo 3}

## Alcance

### Incluido
- {Feature incluida 1}
- {Feature incluida 2}

### Excluido
- {Feature excluida 1}
- {Feature excluida 2}

## Arquitectura
{Diagrama ASCII o descripcion de arquitectura}

## Entregables

| Entregable | Archivo/Ubicacion | Estado |
|------------|-------------------|--------|
| {Entregable 1} | {ruta} | {estado} |

## Dependencias

### Depende de
- {Epica/Modulo del que depende}

### Bloquea a
- {Epica/Modulo que bloquea}

## Criterios de Aceptacion
- [ ] {Criterio 1}
- [ ] {Criterio 2}
- [ ] {Criterio 3}

## Notas Tecnicas
{Consideraciones tecnicas importantes}

## Historias de Usuario Relacionadas
- [US-{ID}](ruta/al/archivo.md)

---

**Ultima actualizacion:** {YYYY-MM-DD}
**Autor:** {Rol/Nombre}

B2: TEMPLATE-MODULO-ESTANDAR.md

# {ID}: {Nombre Modulo}

## Metadata
- **Codigo:** {ID}
- **Modulo:** {Nombre}
- **Prioridad:** {P0|P1|P2}
- **Estado:** {Completado|Implementado|Documentacion}
- **Fase:** {N} - {Nombre Fase}

## Descripcion
{Parrafo con proposito del modulo}

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

## Alcance

### Incluido
- {Feature incluida}

### Excluido
- {Feature excluida}

## Modelo de Datos

### Tablas (schema: {schema_name})

**{nombre_tabla}**
| Columna | Tipo | Descripcion |
|---------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK tenants |
| {campo} | {tipo} | {descripcion} |
| created_at | TIMESTAMP | Fecha creacion |
| updated_at | TIMESTAMP | Fecha actualizacion |

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/{recurso} | Crear |
| GET | /api/{recurso} | Listar |
| GET | /api/{recurso}/:id | Obtener |
| PUT | /api/{recurso}/:id | Actualizar |
| DELETE | /api/{recurso}/:id | Eliminar |

## Configuracion

### Variables de Entorno
```env
{PREFIJO}_{VARIABLE}={valor_ejemplo}

Roadmap / Estado

Feature	Estado	Prioridad
{Feature}	{estado}	{P0-P3}

---

Ultima actualizacion: {YYYY-MM-DD}

#### B3: TEMPLATE-MAP-INDICE.md

```markdown
# _MAP: {Nombre Seccion}

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

---

## Resumen

| Metrica | Valor |
|---------|-------|
| Total archivos | {N} |
| Documentos completados | {N} |
| Documentos pendientes | {N} |
| Progreso | {N}% |

---

## Contenido

| Archivo | Tipo | Estado | Descripcion |
|---------|------|--------|-------------|
| [{archivo.md}](./{archivo.md}) | {tipo} | {estado} | {descripcion} |

---

## Navegacion por Caso de Uso

### Para {caso de uso 1}:
1. Leer [{archivo}](./{archivo})
2. Revisar [{archivo}](./{archivo})

### Para {caso de uso 2}:
1. Consultar [{archivo}](./{archivo})

---

## Subdirectorios

| Directorio | Descripcion | Archivos |
|------------|-------------|----------|
| [{dir}/](./{dir}/) | {descripcion} | {N} |

---

## Referencias Externas
- [{Referencia}](../ruta/archivo.md)

---

**Mantenido por:** {Rol}
**Version:** {SEMVER}

B4: TEMPLATE-INVENTARIO-PROYECTO.md

# Inventario: {TIPO}
# Proyecto: {nombre}
# Version: {SEMVER}
# Actualizado: {YYYY-MM-DD}

metadata:
  proyecto: "{nombre}"
  tipo: "{MASTER|DATABASE|BACKEND|FRONTEND}"
  version: "{SEMVER}"
  updated: "{YYYY-MM-DD}"

# Para MASTER_INVENTORY
resumen:
  progreso_mvp: "{N}%"
  story_points_completados: {N}
  story_points_totales: {N}
  tareas_completadas: {N}
  tareas_totales: {N}

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

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

# Para DATABASE_INVENTORY
schemas:
  - nombre: "{schema}"
    descripcion: "{descripcion}"
    tablas:
      - nombre: "{tabla}"
        columnas: {N}
        estado: "{implementada|pendiente}"

# Para BACKEND_INVENTORY
modulos:
  - nombre: "{modulo}"
    ruta: "{ruta/relativa}"
    controllers: {N}
    services: {N}
    endpoints: {N}
    estado: "{implementado|pendiente}"

# Para FRONTEND_INVENTORY
paginas:
  - nombre: "{pagina}"
    ruta: "{ruta/relativa}"
    componentes: {N}
    estado: "{implementada|pendiente}"

B5: TEMPLATE-INTEGRACION-EXTERNA.md

# INT-{NNN}: {Nombre Integracion}

## Metadata
- **Codigo:** INT-{NNN}
- **Proveedor:** {Nombre del proveedor}
- **Tipo:** {Pagos|Auth|Notificaciones|Storage|etc}
- **Estado:** {Implementado|Documentado|Pendiente}
- **Multi-tenant:** {Si|No}

## Descripcion
{Proposito de la integracion}

## Credenciales Requeridas

| Variable de Entorno | Descripcion | Requerido |
|---------------------|-------------|-----------|
| {PREFIJO}_{VAR} | {descripcion} | {Si|No} |

## Endpoints/SDK Utilizados

| Operacion | Endpoint/Metodo | Descripcion |
|-----------|-----------------|-------------|
| {operacion} | {endpoint} | {descripcion} |

## Rate Limits
- {limite}: {valor}

## Manejo de Errores

| Codigo | Descripcion | Accion |
|--------|-------------|--------|
| {codigo} | {descripcion} | {accion} |

## Fallbacks
- {Estrategia de fallback si aplica}

## Multi-tenant
{Descripcion de como funciona en multi-tenant}

## Testing
```bash
# Comando para probar integracion
{comando}

Referencias

• Documentacion oficial
• Modulo relacionado

---

Ultima actualizacion: {YYYY-MM-DD}

---

### 3.3 BLOQUE C: Checklists

#### C1: CHECKLIST-DOCUMENTACION-PROYECTO.md

```markdown
# Checklist: Documentacion de Proyecto

## Estructura de /docs

- [ ] Existe directorio /docs en raiz del proyecto
- [ ] Existe /docs/_MAP.md como indice principal
- [ ] Existe /docs/README.md
- [ ] Existe /docs/00-vision-general/
- [ ] Existen directorios de fases numerados (01-, 02-, etc.)
- [ ] Existe /docs/90-transversal/ si aplica
- [ ] Existe /docs/97-adr/ si hay decisiones arquitectonicas

## Estructura de /orchestration

- [ ] Existe directorio /orchestration
- [ ] Existe CONTEXT-MAP.yml
- [ ] Existe PROJECT-STATUS.md
- [ ] Existe /orchestration/inventarios/
- [ ] Existe MASTER_INVENTORY.yml
- [ ] Existe 00-guidelines/HERENCIA-SIMCO.md o HERENCIA-DIRECTIVAS.md

## Archivos Minimos

- [ ] _MAP.md en cada directorio principal
- [ ] README.md en /docs raiz
- [ ] Al menos un inventario YAML

## Nomenclatura

- [ ] Archivos siguen patron establecido (RF-, ET-, US-, etc.)
- [ ] Directorios usan numeracion y kebab-case
- [ ] Fechas en formato YYYY-MM-DD

## Contenido

- [ ] Documentos tienen metadata (frontmatter o tabla)
- [ ] IDs son unicos y siguen patron
- [ ] Estados son consistentes
- [ ] Referencias cruzadas funcionan

C2: CHECKLIST-INVENTARIOS.md

# Checklist: Inventarios YAML

## MASTER_INVENTORY.yml

- [ ] Existe el archivo
- [ ] Tiene campo metadata (proyecto, version, updated)
- [ ] Tiene campo resumen con progreso
- [ ] Tiene listado de fases
- [ ] Tiene listado de aplicaciones
- [ ] Fecha updated es reciente

## DATABASE_INVENTORY.yml

- [ ] Existe el archivo
- [ ] Lista todos los schemas
- [ ] Cada schema tiene tablas documentadas
- [ ] Estados son correctos (implementada/pendiente)

## BACKEND_INVENTORY.yml

- [ ] Existe el archivo
- [ ] Lista todos los modulos
- [ ] Cuenta de controllers y services es correcta
- [ ] Estados reflejan realidad

## FRONTEND_INVENTORY.yml

- [ ] Existe el archivo
- [ ] Lista todas las paginas
- [ ] Cuenta de componentes es correcta
- [ ] Estados reflejan realidad

## Validacion General

- [ ] YAML es valido (sin errores de sintaxis)
- [ ] Datos son consistentes entre inventarios
- [ ] Numeros coinciden con codigo real

C3: CHECKLIST-NOMENCLATURA.md

# Checklist: Nomenclatura

## Archivos

- [ ] Requerimientos: RF-{MODULO}-{NUM}.md
- [ ] Especificaciones: ET-{TIPO}-{MODULO}.md
- [ ] User Stories: US-{EPICA}-{NUM}-{desc}.md
- [ ] ADRs: ADR-{NUM}-{descripcion}.md
- [ ] Planes: PLAN-{DESC}-{FECHA}.md
- [ ] Analisis: ANALISIS-{DESC}-{FECHA}.md
- [ ] Reportes: REPORTE-{DESC}-{FECHA}.md
- [ ] Trazas: TRAZA-{TIPO}-{DESC}.md
- [ ] Inventarios: {TIPO}_INVENTORY.yml
- [ ] Indices: _MAP.md

## Directorios

- [ ] Vision: 00-vision-general/
- [ ] Fases: {NN}-fase-{nombre}/ o {NN}-{nombre}/
- [ ] Transversal: 90-transversal/
- [ ] Guias: 95-guias-desarrollo/
- [ ] Quick ref: 96-quick-reference/
- [ ] ADRs: 97-adr/
- [ ] Finiquito: 99-finiquito/

## IDs

- [ ] Epicas: EAI-{NUM}, EXT-{NUM}, MCH-{NUM}, MGN-{NUM}
- [ ] Modulos: SAAS-{NUM}
- [ ] Numeracion secuencial sin saltos
- [ ] IDs unicos en todo el proyecto

## Fechas

- [ ] Formato ISO 8601: YYYY-MM-DD
- [ ] En nombres de archivo cuando aplica
- [ ] En metadata de documentos

---

4. ORDEN DE EJECUCION

Sprint 1: Directivas Base (P0)

Dia 1-2:
├── A1: SIMCO-DOCUMENTACION-PROYECTO.md
├── A2: SIMCO-NOMENCLATURA.md
└── A3: SIMCO-ESTRUCTURA-DOCS.md

Dia 3:
├── A5: SIMCO-TESTING.md
└── A6: SIMCO-MIGRACIONES-BD.md

Sprint 2: Templates y Checklists (P0)

Dia 1:
├── B1: TEMPLATE-EPICA-ESTANDAR.md
├── B2: TEMPLATE-MODULO-ESTANDAR.md
└── B3: TEMPLATE-MAP-INDICE.md

Dia 2:
├── C1: CHECKLIST-DOCUMENTACION-PROYECTO.md
└── C3: CHECKLIST-NOMENCLATURA.md

Sprint 3: Complementarios (P1)

Dia 1:
├── A4: SIMCO-INVENTARIOS.md
├── A7: SIMCO-INTEGRACIONES-EXTERNAS.md
└── B4: TEMPLATE-INVENTARIO-PROYECTO.md

Dia 2:
├── B5: TEMPLATE-INTEGRACION-EXTERNA.md
└── C2: CHECKLIST-INVENTARIOS.md

Sprint 4: Indices y Actualizaciones (P0)

Dia 1:
├── D1: INDICE-DIRECTIVAS-WORKSPACE.yml
├── D2: orchestration/directivas/simco/_MAP.md
├── D3: orchestration/templates/_MAP.md
└── D4: orchestration/checklists/_MAP.md

Dia 2:
└── D5: shared/knowledge-base/standards/

Sprint 5: Integracion en Proyectos (P1-P2)

Dia 1-2:
├── E3: michangarrito (aplicar estandares)
└── E4: template-saas (aplicar estandares)

Dia 3:
├── E1: gamilit (validar conformidad)
└── E2: erp-core (validar conformidad)

---

5. DEPENDENCIAS ENTRE TAREAS

A1 (SIMCO-DOCUMENTACION) ─────┬─────> B1 (TEMPLATE-EPICA)
                              ├─────> B2 (TEMPLATE-MODULO)
                              └─────> C1 (CHECKLIST-DOCS)

A2 (SIMCO-NOMENCLATURA) ──────┬─────> B3 (TEMPLATE-MAP)
                              └─────> C3 (CHECKLIST-NOMENCLATURA)

A3 (SIMCO-ESTRUCTURA-DOCS) ───┬─────> B1 (TEMPLATE-EPICA)
                              └─────> B2 (TEMPLATE-MODULO)

A4 (SIMCO-INVENTARIOS) ───────┬─────> B4 (TEMPLATE-INVENTARIO)
                              └─────> C2 (CHECKLIST-INVENTARIOS)

A7 (SIMCO-INTEGRACIONES) ─────────> B5 (TEMPLATE-INTEGRACION)

Todos (A*, B*, C*) ──────────────> D* (Indices)

D* (Indices) ────────────────────> E* (Proyectos)

---

6. ARCHIVOS A CREAR (RESUMEN)

Directivas (7 archivos)

/orchestration/directivas/simco/
├── SIMCO-DOCUMENTACION-PROYECTO.md   [NUEVO]
├── SIMCO-NOMENCLATURA.md             [NUEVO]
├── SIMCO-ESTRUCTURA-DOCS.md          [NUEVO]
├── SIMCO-INVENTARIOS.md              [NUEVO]
├── SIMCO-TESTING.md                  [NUEVO]
├── SIMCO-MIGRACIONES-BD.md           [NUEVO]
└── SIMCO-INTEGRACIONES-EXTERNAS.md   [NUEVO]

Templates (5 archivos)

/orchestration/templates/
├── TEMPLATE-EPICA-ESTANDAR.md        [NUEVO]
├── TEMPLATE-MODULO-ESTANDAR.md       [NUEVO]
├── TEMPLATE-MAP-INDICE.md            [NUEVO]
├── TEMPLATE-INVENTARIO-PROYECTO.md   [NUEVO]
└── TEMPLATE-INTEGRACION-EXTERNA.md   [NUEVO]

Checklists (3 archivos)

/orchestration/checklists/
├── CHECKLIST-DOCUMENTACION-PROYECTO.md  [NUEVO]
├── CHECKLIST-INVENTARIOS.md             [NUEVO]
└── CHECKLIST-NOMENCLATURA.md            [NUEVO]

Actualizaciones (5 archivos)

/orchestration/INDICE-DIRECTIVAS-WORKSPACE.yml     [ACTUALIZAR]
/orchestration/directivas/simco/_MAP.md            [ACTUALIZAR]
/orchestration/templates/_MAP.md                   [ACTUALIZAR]
/orchestration/checklists/_MAP.md                  [CREAR]
/shared/knowledge-base/standards/                  [AGREGAR]

Total: 20 archivos

---

7. METRICAS DE EXITO

Metrica	Objetivo	Validacion
Directivas creadas	7/7	Contar archivos
Templates creados	5/5	Contar archivos
Checklists creados	3/3	Contar archivos
Indices actualizados	5/5	Verificar links
Proyectos validados	4/4	Ejecutar checklists
Conformidad promedio	>4.0	Matriz de madurez

---

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