Skip to content

🧠 AudioLab Universal Workflow Methodology

📜 FILOSOFÍA: Workflow Profesional y Trazable

Este documento define el ESTÁNDAR DE TRABAJO para AudioLab. Todos los proyectos, auditorías, refactors, y features siguen este proceso.

🎯 PRINCIPIOS FUNDAMENTALES

1. AUDITAR antes de Actuar

❌ No empezar sin entender el estado actual ✅ Documentar QUÉ hay, QUÉ falta, QUÉ funciona

2. DISEÑAR antes de Implementar

❌ No codificar sin plan ✅ Plan de acción detallado, dividido en tareas

3. TAREA A TAREA, sin perder el hilo

❌ No hacer todo a la vez ✅ Una tarea completamente, luego siguiente

4. TRAZABILIDAD total

❌ No perder historial de decisiones ✅ Cada tarea documentada: por qué, cómo, resultado

5. PROFESIONALISMO Canon

❌ No "just make it work" ✅ Hacerlo bien, documentado, mantenible

🔄 EL PROCESO (5 FASES)

┌─────────────────────────────────────────────────────────────┐
│                     WORKFLOW UNIVERSAL                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. AUDIT     → Entender estado actual                      │
│      ↓                                                       │
│  2. DESIGN    → Crear plan de acción                        │
│      ↓                                                       │
│  3. DIVIDE    → Dividir en tareas atómicas                  │
│      ↓                                                       │
│  4. EXECUTE   → Implementar tarea a tarea                   │
│      ↓                                                       │
│  5. VERIFY    → Verificar y documentar                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

📋 FASE 1: AUDIT (Auditoría)

Objetivo

Entender el estado actual del sistema/componente/feature.

Entregables

  • AUDIT_REPORT.md con:
  • ✅ QUÉ EXISTE: Componentes, archivos, funcionalidad
  • ⚠️ QUÉ FALTA: Gaps, problemas, deuda técnica
  • 🔴 QUÉ ESTÁ ROTO: Bugs, tests fallando, performance
  • 📊 MÉTRICAS: Números concretos (cobertura, LOC, etc.)

Ejemplo

# AUDIT: 04_CORE Testing System

## Estado Actual
- Tests existentes: 74 archivos
- Tests compilados: 0 ❌
- Cobertura: Desconocida

## Problemas
1. Catch2 no integrado
2. Tests excluidos del build
3. Sin CI/CD

## Métricas
- LOC: 15,000
- Test LOC: 8,000
- Ratio: 1.9 (bueno)

🎨 FASE 2: DESIGN (Diseño del Plan)

Objetivo

Crear plan de acción detallado y priorizado.

Entregables

  • ACTION_PLAN.md con:
  • 🎯 OBJETIVOS: Qué lograr (medible)
  • 🚀 FASES: División en bloques lógicos
  • 📝 TAREAS: Lista completa de tareas
  • ⏱️ ESTIMACIÓN: Tiempo estimado por tarea
  • 🔄 DEPENDENCIAS: Qué depende de qué

Estructura del Plan

# ACTION PLAN: [Nombre del Proyecto]

## Objetivos
- [ ] Objetivo 1 (métrica: X%)
- [ ] Objetivo 2 (métrica: Y tests pasando)

## Fases

### FASE 1: Foundation (2h)
- Tarea 1.1: Setup Catch2 (30min)
- Tarea 1.2: Configure CMake (1h)

### FASE 2: Verification (4h)
- Tarea 2.1: Compile tests (2h)
- Tarea 2.2: Run tests (1h)

✂️ FASE 3: DIVIDE (Dividir en Tareas)

Objetivo

Convertir plan en tareas atómicas y ejecutables.

Características de una Buena Tarea

  • ✅ Atómica: Se hace en 1 sesión (<2h)
  • ✅ Verificable: Claro cuándo está completa
  • ✅ Independiente: Puede hacerse sola (o con deps claras)
  • ✅ Documentada: Template con contexto

Estructura de Tarea

# TASK-001: [Nombre Descriptivo]

## Contexto
Por qué esta tarea es necesaria.

## Objetivo
Qué lograr específicamente.

## Pasos
1. Paso 1
2. Paso 2
3. Paso 3

## Verificación
Cómo saber que está completa.

## Dependencias
- [ ] TASK-000 (debe estar completa)

## Estimación
30 minutos

## Estado
[ ] TODO
[ ] IN_PROGRESS
[ ] BLOCKED
[ ] COMPLETED

⚙️ FASE 4: EXECUTE (Ejecución)

Objetivo

Implementar tareas una a una, sin perder foco.

Proceso por Tarea

1. Seleccionar Tarea

# Mover de templates a in_progress
mv _BRAIN/tasks/templates/TASK-001.md _BRAIN/tasks/in_progress/

2. Marcar como In Progress

## Estado
[x] IN_PROGRESS

3. Ejecutar Pasos

Seguir los pasos documentados.

4. Verificar Completion

Comprobar criterios de verificación.

5. Completar Tarea

## Estado
[x] COMPLETED

## Resultado
[Documentar qué se hizo y resultado]

## Fecha
2025-10-17 01:30

6. Mover a Completed

mv _BRAIN/tasks/in_progress/TASK-001.md _BRAIN/tasks/completed/

✅ FASE 5: VERIFY (Verificación)

Objetivo

Asegurar que todo funciona y está documentado.

Checklist de Verificación

A nivel de Tarea

  • Código compila
  • Tests pasan
  • Documentación actualizada
  • Sin warnings críticos
  • Commit hecho

A nivel de Fase

  • Todas las tareas completadas
  • Objetivos de fase cumplidos
  • Integration tests pasan
  • Documentación de fase completa

A nivel de Proyecto

  • Todas las fases completadas
  • Objetivos del proyecto cumplidos
  • AUDIT final vs inicial
  • Post-mortem documentado

📁 ESTRUCTURA DE DIRECTORIOS

_BRAIN/
├── workflows/                      # Metodologías y procesos
│   ├── WORKFLOW_METHODOLOGY.md    # Este documento
│   └── [otros workflows]
│
├── tasks/
│   ├── templates/                 # Templates de tareas
│   │   ├── TASK-001.md
│   │   ├── TASK-002.md
│   │   └── TASK-NNN.md
│   │
│   ├── in_progress/               # Tareas activas
│   │   └── TASK-003.md
│   │
│   └── completed/                 # Tareas terminadas (historial)
│       ├── 2025-10-17_TASK-001.md
│       └── 2025-10-17_TASK-002.md
│
└── projects/                      # Planes de acción por proyecto
    ├── 001_CORE_TESTING/
    │   ├── AUDIT_REPORT.md
    │   ├── ACTION_PLAN.md
    │   ├── PROGRESS.md
    │   └── POST_MORTEM.md
    │
    └── 002_[NEXT_PROJECT]/

🎯 CONVENCIONES DE NOMENCLATURA

Proyectos

NNN_PROJECT_NAME/
├─ AUDIT_REPORT.md       # Auditoría inicial
├─ ACTION_PLAN.md        # Plan de acción
├─ PROGRESS.md           # Tracking de progreso
└─ POST_MORTEM.md        # Análisis final

Tareas

TASK-NNN: [Verbo] [Objeto] [Contexto]

Ejemplos:
TASK-001: Integrate Catch2 for CORE Testing
TASK-002: Compile RingBuffer Unit Tests
TASK-003: Execute Lock-Free Queue Tests

Estados

  • TODO: Por hacer
  • IN_PROGRESS: En desarrollo activo
  • BLOCKED: Bloqueada por dependencia
  • COMPLETED: Terminada y verificada

📊 TRACKING DE PROGRESO

PROGRESS.md (Se actualiza continuamente)

# Progress Tracking: [Project Name]

## Overall Status
**Started**: 2025-10-17
**Target**: 2025-10-20
**Progress**: 45% (9/20 tasks)

## By Phase

### PHASE 1: Foundation ✅ COMPLETED
- [x] TASK-001: Integrate Catch2
- [x] TASK-002: Configure CMake
- [x] TASK-003: Create test targets

### PHASE 2: Verification 🔄 IN PROGRESS
- [x] TASK-004: Compile RingBuffer tests
- [x] TASK-005: Compile Parameter tests
- [ ] TASK-006: Run all unit tests
- [ ] TASK-007: Analyze failures

### PHASE 3: Coverage ⏳ TODO
- [ ] TASK-008: Setup coverage tools
- [ ] TASK-009: Measure coverage
- [ ] TASK-010: Fix gaps

## Blockers
- None currently

## Notes
- Catch2 integration took longer than expected (1.5h vs 30min)
- All tests compile but 3 fail (investigating)

🔬 EJEMPLO COMPLETO: Workflow en Acción

Proyecto: "04_CORE Testing System"

1. AUDIT

Creamos: _BRAIN/projects/001_CORE_TESTING/AUDIT_REPORT.md - Encontramos: 74 tests, 0 ejecutados - Problemas: Catch2, CI/CD, cobertura

2. DESIGN

Creamos: _BRAIN/projects/001_CORE_TESTING/ACTION_PLAN.md - 3 fases - 15 tareas - 12 horas estimadas

3. DIVIDE

Creamos tareas en: _BRAIN/tasks/templates/ - TASK-001 a TASK-015 - Cada una con contexto, pasos, verificación

4. EXECUTE

# Día 1: FASE 1
mv tasks/templates/TASK-001.md tasks/in_progress/
# Trabajo en TASK-001
# Completo y verifico
mv tasks/in_progress/TASK-001.md tasks/completed/2025-10-17_TASK-001.md

# Siguiente tarea
mv tasks/templates/TASK-002.md tasks/in_progress/
# ...

5. VERIFY

Al final de cada fase: - Checklist de verificación - Update PROGRESS.md - Integration tests

🎓 BEST PRACTICES

DO ✅

  • Auditar ANTES de diseñar
  • Diseñar ANTES de codificar
  • Una tarea a la vez
  • Documentar decisiones
  • Verificar antes de siguiente tarea
  • Mantener PROGRESS.md actualizado
  • Hacer commits por tarea

DON'T ❌

  • No saltar fases
  • No hacer múltiples tareas en paralelo
  • No dejar tareas "casi terminadas"
  • No perder trazabilidad
  • No hacer "quick fixes" sin documentar
  • No ignorar tests

📈 MÉTRICAS DE ÉXITO

Por Proyecto

  • Tiempo real vs estimado
  • Tareas completadas vs planeadas
  • Objetivos logrados (%)
  • Deuda técnica reducida

Por Sistema (AudioLab)

  • Proyectos completados
  • Cobertura de tests (%)
  • Bugs encontrados y arreglados
  • Documentación actualizada

🔄 MEJORA CONTINUA

Post-Mortem (Después de cada proyecto)

# Post-Mortem: [Project Name]

## What Went Well ✅
- Qué funcionó bien
- Qué repetiríamos

## What Went Wrong ❌
- Qué falló
- Qué evitaríamos

## Lessons Learned 🎓
- Aprendizajes clave
- Mejoras al proceso

## Action Items 🚀
- [ ] Actualizar templates
- [ ] Mejorar estimaciones
- [ ] Nuevo checklist

🎯 RESUMEN EJECUTIVO

El Ciclo Completo

AUDIT → DESIGN → DIVIDE → EXECUTE → VERIFY
  ↓        ↓        ↓         ↓         ↓
Report   Plan    Tasks    Code      Check
  ↓        ↓        ↓         ↓         ↓
.md      .md      .md      git      tests

Outputs Clave

  1. AUDIT_REPORT.md - Qué hay
  2. ACTION_PLAN.md - Qué hacer
  3. TASK-NNN.md - Cómo hacerlo
  4. PROGRESS.md - Dónde estamos
  5. POST_MORTEM.md - Qué aprendimos

Beneficios

  • ✅ Claridad: Siempre sabemos qué hacer
  • ✅ Trazabilidad: Historial completo de decisiones
  • ✅ Profesionalismo: Proceso industrial-grade
  • ✅ Escalabilidad: Funciona para proyectos grandes
  • ✅ Calidad: Verificación en cada paso

Este es el estándar. Todos los proyectos AudioLab siguen este workflow.

Versión: 1.0.0 Creado: 2025-10-17 Autor: AudioLab Core Team Status: CANON ✅