Motion Studio SDLC

Manual de Ejecución del SDLC para Motion Studio

Cuando se te pida implementar una funcionalidad o corregir un error en este repositorio, ejecuta estos pasos exactos en orden:

Paso 1: Sincronización de Contratos (Control de Especificación)

1. Inspecciona engine/schemas.py y remotion/src/types.ts.
2. Agrega o modifica campos para satisfacer los requisitos de la funcionalidad.
3. Valida que los modelos Pydantic compilen:

   python3 -c "import engine.schemas as s; print('Schemas OK')"
   

   (Nota: Si existe un virtualenv del proyecto, invócalo mediante .venv/bin/python3).
4. Nunca pases al código de implementación hasta que los contratos estén alineados en ambos lenguajes.

Paso 2: Fase Roja (Escribir Pruebas Fallidas)

1. Escribe un nuevo archivo de prueba o caso de prueba bajo tests/ (Pytest) o remotion/src/__tests__/ (Vitest/Jest).
2. Verifica la validación del esquema, casos límite y la salida serializada esperada.
3. Ejecuta la prueba y confirma el fallo:

   pytest tests/
   # Si el lanzador de pruebas del frontend está configurado en remotion/package.json:
   npm --prefix remotion test -- --run
   

4. Registra el rastro del fallo. Si la prueba pasa de inmediato, reescríbela para probar la nueva capacidad real. La fase Roja se cumple solo cuando las pruebas fallan con las aserciones esperadas.

Paso 3: Fase Verde (Implementación Mínima)

1. Escribe el código mínimo en engine/ o remotion/src/ para que la prueba pase.
2. En Remotion, adhiérete estrictamente a la Ley de Fotograma Determinista:
   • La derivación debe provenir estrictamente de useCurrentFrame() y useVideoConfig().
   • Nunca uses Date.now(), Math.random() o requestAnimationFrame() sin límite.
3. Preserva los patrones arquitectónicos existentes (<Series>, <Sequence>, <ThreeScene>, <KineticScene>).
4. Asegúrate de que los activos vectoriales conserven IDs y clases según remotion/svgo.config.mjs para la orientación de GSAP.

Paso 4: Control de Calidad y Bucle de Autocuración Automatizado

Lleva la cuenta del contador de iteraciones del bucle (ATTEMPT ∈ {1, 2, 3}). Ejecuta cada control secuencialmente sin enmascarar códigos de salida (no añadas || true):

# Nivel 1: Análisis de Tipos Estáticos
python3 -m mypy engine/schemas.py engine/api.py
npm --prefix remotion run build -- --bundle-cache=false

# Nivel 2: Suites de Pruebas Automatizadas
pytest tests/
# Si el lanzador de pruebas del frontend está configurado en remotion/package.json:
npm --prefix remotion test -- --run

# Nivel 3: Rasterización de Fotogramas con Chromium sin Interfaz Gráfica
(cd remotion && npx remotion still src/index.ts MainComposition /tmp/smoke.png \
  --props='{"scenes":[],"theme":{}}' \
  --gl=angle \
  --overwrite)

Política de Autocuración y Reversión

• En Caso de Error (Intento 1 o 2):

  1. Captura la ruta exacta del archivo, el número de línea que falla y el error estándar/trazado.
  2. Implementa un parche mínimo y específico que aborde estrictamente el error reportado.
  3. Incrementa ATTEMPT y reinicia el Nivel 1.

• En Caso de Error (Intento 3 – Presupuesto Agotado): Detén inmediatamente las modificaciones especulativas y revierte solo los archivos de funcionalidad modificados y creados (nunca realices una limpieza global general):

  # Plan de Contingencia por Agotamiento del Nivel 4: Apuntar solo a ámbitos de código de funcionalidad
  git restore --staged --worktree engine/ remotion/ tests/
  git clean -fd engine/ remotion/ tests/
  rm -f /tmp/smoke.png
  echo "El control de calidad falló tras 3 intentos. Rutas de código objetivo restauradas a la línea base limpia."
  exit 1
  

  (Alternativa para conservar trabajo para un análisis posterior al incidente: git stash push -u -m "sdlc-failed-attempt-$(date +%s)" -- engine/ remotion/ tests/)

• En Caso de Éxito (Todos los Niveles Salen con 0): Elimina los artefactos transitorios y crea el commit verificado:

  rm -f /tmp/smoke.png
  git add engine/ remotion/ tests/
  git commit -m "feat(motion-sdlc): implementar funcionalidad verificada con puerta de prueba verde"