# Templates de Checkpoints — Referencia Rápida

Copia el template del tipo correcto y rellena los campos marcados con `[...]`.
Elimina los comentarios `<!-- ... -->` antes de emitir el checkpoint.

---

## Tipo 1: human-verify

Usar cuando el agente terminó trabajo y el humano debe confirmar calidad antes de continuar.

```xml
<checkpoint type="human-verify" id="verify-[identificador-unico]" auto_advance="false">
  <titulo>[Qué se hizo — frase corta descriptiva]</titulo>

  <resumen>
    [2-4 oraciones describiendo qué se implementó, qué decisiones se tomaron
    y cuál es el estado actual. Ser concreto: números, archivos, resultados.]
  </resumen>

  <artefactos>
    <artefacto tipo="archivo" ruta="[ruta/al/archivo.md]" />
    <artefacto tipo="archivo" ruta="[ruta/al/otro.py]" />
    <!-- tipo puede ser: archivo | log | url | directorio -->
  </artefactos>

  <metricas>
    <metrica nombre="tareas_completadas" valor="[N]" />
    <metrica nombre="tareas_totales" valor="[N]" />
    <metrica nombre="tests_pasando" valor="[N]" />
    <metrica nombre="cobertura_pct" valor="[N]" />
    <!-- Agregar métricas relevantes al contexto -->
  </metricas>

  <preguntas>
    <!-- Opcional: preguntas específicas que el humano debe considerar -->
    <pregunta id="q1">[Pregunta concreta sobre el trabajo entregado]</pregunta>
    <pregunta id="q2">[Pregunta sobre riesgo o edge case identificado]</pregunta>
  </preguntas>

  <opciones>
    <opcion valor="aprobar">Aprobar y continuar con [siguiente paso]</opcion>
    <opcion valor="ajustar">Ajustar con feedback específico</opcion>
    <opcion valor="rechazar">Rechazar y rehacer desde [punto de reintento]</opcion>
  </opciones>
</checkpoint>
```

### Ejemplo concreto: verificación de slice de autenticación

```xml
<checkpoint type="human-verify" id="verify-auth-slice1" auto_advance="false">
  <titulo>Slice 1 completo: modelos y endpoints de autenticación JWT</titulo>

  <resumen>
    Se implementaron los modelos Usuario y Sesion con migraciones Alembic,
    los endpoints /auth/login y /auth/refresh con RBAC, y los schemas Pydantic
    correspondientes. La cobertura de tests es 94%. El linter y mypy pasan sin errores.
  </resumen>

  <artefactos>
    <artefacto tipo="archivo" ruta="app/models/usuario.py" />
    <artefacto tipo="archivo" ruta="app/routers/auth.py" />
    <artefacto tipo="archivo" ruta="tests/test_auth.py" />
    <artefacto tipo="archivo" ruta="alembic/versions/001_usuarios.py" />
  </artefactos>

  <metricas>
    <metrica nombre="endpoints_implementados" valor="2" />
    <metrica nombre="tests_pasando" valor="18" />
    <metrica nombre="cobertura_pct" valor="94" />
    <metrica nombre="errores_mypy" valor="0" />
  </metricas>

  <preguntas>
    <pregunta id="q1">¿El tiempo de expiración del token (24h) coincide con el requerimiento de negocio?</pregunta>
    <pregunta id="q2">¿Se requiere soporte para múltiples sesiones simultáneas o solo la sesión más reciente?</pregunta>
  </preguntas>

  <opciones>
    <opcion valor="aprobar">Aprobar y continuar con Slice 2 (CRUD de usuarios)</opcion>
    <opcion valor="ajustar">Ajustar con feedback específico antes de Slice 2</opcion>
    <opcion valor="rechazar">Rechazar y rehacer el slice desde los modelos</opcion>
  </opciones>
</checkpoint>
```

### Variante auto_advance (informativo, sin pausa)

Usar cuando el resultado es positivo y no requiere confirmación explícita:

```xml
<checkpoint type="human-verify" id="verify-lint-[fase]" auto_advance="true">
  <titulo>Lint, type-check y tests pasaron — continuando automáticamente</titulo>

  <resumen>
    Todos los archivos del Slice [N] pasaron ruff, mypy y pytest sin errores.
    Se continúa automáticamente con el Slice [N+1].
  </resumen>

  <artefactos>
    <artefacto tipo="log" ruta=".claude/logs/lint-[fecha].txt" />
  </artefactos>

  <metricas>
    <metrica nombre="errores_ruff" valor="0" />
    <metrica nombre="errores_mypy" valor="0" />
    <metrica nombre="tests_pasando" valor="[N]" />
  </metricas>
</checkpoint>
```

---

## Tipo 2: decision

Usar cuando hay una bifurcación real donde ambas opciones son válidas y el humano
debe elegir según criterios de negocio, riesgo o prioridad que el agente no puede resolver.

```xml
<checkpoint type="decision" id="decision-[dominio]-[tema]" auto_advance="false">
  <titulo>[Decisión que se necesita — formulada como pregunta o elección]</titulo>

  <contexto>
    [Explicar por qué se llegó a esta bifurcación. Qué dice (o no dice) la spec.
    Qué consecuencias tiene cada camino. 3-5 oraciones máximo.]
  </contexto>

  <opciones>
    <opcion id="A" recomendada="false">
      <!-- recomendada="true" en la opción que el agente recomienda -->
      <nombre>[Nombre corto de la opción A]</nombre>
      <pros>
        <pro>[Ventaja concreta y medible]</pro>
        <pro>[Otra ventaja]</pro>
      </pros>
      <contras>
        <contra>[Desventaja concreta]</contra>
        <contra>[Otra desventaja]</contra>
      </contras>
      <impacto>[Impacto en tiempo, costo, riesgo o mantenimiento. Sé específico.]</impacto>
    </opcion>

    <opcion id="B" recomendada="true">
      <nombre>[Nombre corto de la opción B]</nombre>
      <pros>
        <pro>[Ventaja]</pro>
      </pros>
      <contras>
        <contra>[Desventaja]</contra>
      </contras>
      <impacto>[Impacto]</impacto>
    </opcion>

    <!-- Agregar opción C solo si genuinamente hay 3 caminos distintos.
         Máximo 4 opciones por checkpoint. -->
  </opciones>

  <recomendacion>
    [Párrafo explicando por qué el agente recomienda la opción marcada.
    Fundamentar con criterios técnicos, no preferencias. Ser directo.]
  </recomendacion>

  <consecuencias_de_espera>
    [Qué está bloqueado mientras no se toma esta decisión.
    Qué tareas pueden avanzar de forma independiente mientras tanto.]
  </consecuencias_de_espera>
</checkpoint>
```

### Ejemplo concreto: elección de estrategia de migración

```xml
<checkpoint type="decision" id="decision-migracion-schema-v2" auto_advance="false">
  <titulo>Estrategia de migración: big-bang vs incremental para schema v2</titulo>

  <contexto>
    El schema v2 requiere renombrar 12 columnas y agregar 3 tablas nuevas.
    La base de datos de producción tiene 2.3M registros. La spec no especifica
    la estrategia de migración. Hay dos caminos viables con trade-offs distintos.
  </contexto>

  <opciones>
    <opcion id="A" recomendada="false">
      <nombre>Big-bang: migración única con ventana de mantenimiento</nombre>
      <pros>
        <pro>Código más simple: sin lógica de compatibilidad dual</pro>
        <pro>Migración completa en una sola operación atómica</pro>
      </pros>
      <contras>
        <contra>Requiere ventana de mantenimiento de ~45 minutos</contra>
        <contra>Riesgo de rollback complejo si falla a mitad</contra>
      </contras>
      <impacto>Downtime de 45 min. Implementación: 2 días. Sin deuda técnica residual.</impacto>
    </opcion>

    <opcion id="B" recomendada="true">
      <nombre>Incremental: expand-contract pattern (sin downtime)</nombre>
      <pros>
        <pro>Zero downtime: producción nunca se interrumpe</pro>
        <pro>Rollback simple en cualquier punto de la migración</pro>
      </pros>
      <contras>
        <contra>Código temporal de compatibilidad por ~2 semanas</contra>
        <contra>Requiere 3 deployments en lugar de 1</contra>
      </contras>
      <impacto>Sin downtime. Implementación: 5 días. Complejidad temporal gestionable.</impacto>
    </opcion>
  </opciones>

  <recomendacion>
    Se recomienda la opción B (expand-contract) porque la aplicación tiene SLA de
    disponibilidad del 99.5% y 45 minutos de downtime viola ese acuerdo. El coste
    adicional de 3 días de implementación es menor que el riesgo de incumplimiento del SLA.
  </recomendacion>

  <consecuencias_de_espera>
    El Slice 3 (endpoints de reportes) está bloqueado hasta esta decisión.
    Los Slices 1 y 2 (autenticación y CRUD básico) pueden continuar independientemente.
  </consecuencias_de_espera>
</checkpoint>
```

---

## Tipo 3: human-action

Usar cuando el agente necesita que el humano realice una acción fuera del alcance
del agente: configurar credenciales, aprobar gastos, ejecutar en sistemas restringidos, etc.

```xml
<checkpoint type="human-action" id="action-[dominio]-[accion]" auto_advance="false">
  <titulo>[Acción requerida — imperativo claro: "Configurar X", "Aprobar Y", "Ejecutar Z"]</titulo>

  <razon>
    [Por qué el agente no puede hacer esto por sí solo. Ser honesto y específico:
    "No tiene acceso a X", "Requiere autorización de Y", "Está fuera del sandbox".]
  </razon>

  <acciones_requeridas>
    <accion orden="1">
      <descripcion>[Paso concreto y accionable]</descripcion>
      <detalle>
        [Información específica necesaria para completar el paso:
        rutas, IDs, formatos, valores exactos.]
      </detalle>
    </accion>

    <accion orden="2">
      <descripcion>[Siguiente paso]</descripcion>
      <detalle>[Detalles]</detalle>
    </accion>

    <accion orden="N">
      <descripcion>Confirmar aquí cuando todas las acciones anteriores estén completadas</descripcion>
    </accion>
  </acciones_requeridas>

  <bloqueado_hasta>
    [Qué tareas están bloqueadas hasta que estas acciones se completen.
    Ser específico: nombres de tareas, slices o fases.]
  </bloqueado_hasta>

  <tiempo_estimado>[Estimación realista: "5-10 minutos", "1-2 horas", "1 día hábil"]</tiempo_estimado>

  <!-- Opcional: notificación de urgencia -->
  <notificacion>
    <prioridad>urgente</prioridad>
    <canales>desktop,telegram</canales>
    <resumen_corto>BLOQUEADO: [descripción de 60 chars máximo]</resumen_corto>
  </notificacion>
</checkpoint>
```

### Ejemplo concreto: configuración de secretos en producción

```xml
<checkpoint type="human-action" id="action-secrets-produccion" auto_advance="false">
  <titulo>Configurar credenciales de base de datos en gestor de secretos de producción</titulo>

  <razon>
    El agente no tiene acceso al gestor de secretos de producción (AWS Secrets Manager).
    Las credenciales son necesarias para que el pipeline de CI pueda ejecutar las migraciones
    de Alembic contra la base de datos de producción en el siguiente deployment.
  </razon>

  <acciones_requeridas>
    <accion orden="1">
      <descripcion>Acceder a AWS Secrets Manager en la consola de producción</descripcion>
      <detalle>
        Región: us-east-1
        Cuenta AWS: [número de cuenta]
        URL: https://console.aws.amazon.com/secretsmanager/home?region=us-east-1
      </detalle>
    </accion>

    <accion orden="2">
      <descripcion>Crear o actualizar el secreto "sigaf/prod/database"</descripcion>
      <detalle>
        Estructura JSON requerida (copiar exactamente):
        {
          "host": "[hostname RDS de producción]",
          "port": 5432,
          "database": "sigaf_prod",
          "username": "[usuario de producción]",
          "password": "[contraseña segura — mínimo 32 chars, símbolos incluidos]"
        }
      </detalle>
    </accion>

    <accion orden="3">
      <descripcion>Agregar el ARN del secreto como variable en GitHub Actions</descripcion>
      <detalle>
        Settings → Secrets and variables → Actions → New repository secret
        Nombre: PROD_DB_SECRET_ARN
        Valor: arn:aws:secretsmanager:us-east-1:[cuenta]:secret:sigaf/prod/database-[sufijo]
      </detalle>
    </accion>

    <accion orden="4">
      <descripcion>Confirmar aquí que los tres pasos anteriores están completos</descripcion>
    </accion>
  </acciones_requeridas>

  <bloqueado_hasta>
    La tarea "deploy-produccion" y el Slice 4 completo están bloqueados hasta
    completar estas acciones. El desarrollo local puede continuar sin ellas.
  </bloqueado_hasta>

  <tiempo_estimado>10-15 minutos</tiempo_estimado>

  <notificacion>
    <prioridad>urgente</prioridad>
    <canales>desktop,telegram</canales>
    <resumen_corto>BLOQUEADO: Configurar credenciales AWS para deploy a producción</resumen_corto>
  </notificacion>
</checkpoint>
```

---

## Reglas de selección de tipo

| Situación | Tipo correcto |
|-----------|--------------|
| El agente terminó una tarea y quiere confirmación de calidad | `human-verify` |
| El lint/tests pasan, reportar sin bloquear | `human-verify` con `auto_advance="true"` |
| Hay dos opciones técnicas igualmente válidas con distinto impacto | `decision` |
| Hay una opción claramente superior | NO usar `decision` — usar `human-verify` con recomendación |
| El agente necesita credenciales, accesos o aprobaciones externas | `human-action` |
| Necesita que alguien ejecute algo en producción | `human-action` |

## Anti-patrones

- Checkpoint sin `id` único: dificulta la trazabilidad en ESTADO.md
- `auto_advance="true"` en `decision` o `human-action`: nunca válido
- Más de 4 opciones en un `decision`: sobrecarga cognitiva
- `human-action` para algo que el agente puede hacer con sus herramientas disponibles
- `decision` sin campo `recomendacion`: el agente siempre debe tener una posición fundamentada
- Omitir `consecuencias_de_espera` en `decision`: el humano necesita saber qué se bloquea
