# Regla: Comentarios temporales en código NO son verificación

Esta regla es OBLIGATORIA para todo trabajo de Claude en swl-ses. Extiende la
regla global `~/.claude/rules/verificar-citas-normativas.md § Familia 2` con
el sub-caso específico de **comentarios temporales como `// Alineado con
commits X+Y` o `// Refactorizado a vN.M.0`**.

---

## Principio

> Un comentario en código que afirma alineación con otro commit, versión o
> contrato (`// Alineado con commits X+Y`, `// Refactorizado a vN.M.0`,
> `# Sincronizado con backend`, `<!-- Coherente con schema X -->`) **NO es
> verificación** — es afirmación temporal sin prueba. Antes de actuar
> sobre el comentario como si fuera evidencia, verificar contra la fuente
> real con `grep` / `Read` / `git log`.

El comentario puede haberse desactualizado silenciosamente si el commit
referenciado se revirtió, nunca se aplicó, o si el refactor citado cambió
después de escribir el comentario.

---

## Cuándo aplicar

OBLIGATORIO verificar antes de aceptar como evidencia accionable:

- Comentarios `// Alineado con commits <SHA>+<SHA>` en código
- Comentarios `// Refactorizado a v<N.M.0>` o `// Migrado a <framework>`
- Comentarios `# Sincronizado con backend` o `# Espejo del schema X`
- Comentarios `<!-- Tipos coherentes con API vN -->`
- Cualquier afirmación de cross-stack alignment en comentario inline

NO aplica cuando:

- El comentario describe la INTENCIÓN del código (no afirma alineación)
- El comentario es una nota pendiente (`T‍ODO` / `FIXME`) con ticket asociado
- El comentario es una explicación del POR QUÉ (no del QUÉ histórico)

---

## Cómo verificar

Cuando un comentario afirma "alineado con X":

1. Identificar **qué se afirma alineado**: archivo, commit, versión, schema.
2. Localizar la fuente real:
   ```bash
   # Si afirma alineación con commit:
   git show <SHA> -- <archivo-citado>

   # Si afirma alineación con schema/types:
   grep -rn "<campo-clave>" backend/ frontend/ schemas/
   ```
3. Comparar campo por campo. Si hay drift, NO confiar en el comentario.
4. Actualizar el comentario o eliminarlo (un comentario stale es peor que
   ningún comentario).

---

## Caso de origen — sesión SIGAF 2026-05-22

`frontend/.../contratos/models/contrato.models.ts` línea 2 decía:

```typescript
// Alineados con el backend refactorizado (commits 284df74 + 5869ac9)
```

Pero el backend nunca aplicó ese refactor. El frontend enviaba 5 campos
(`monto_total`, `fecha_inicio`, `fecha_termino`, `porcentaje_iva`,
`tipo_contrato_id`) que Pydantic con `extra=ignore` descartaba
silenciosamente. Los contratos se creaban sin monto ni vigencia durante
semanas, hasta que se detectó por triangulación cross-stack (modelo
SQLAlchemy + schema Pydantic + types TypeScript).

El comentario funcionó como **falso anclaje de confianza**: un reviewer
posterior lo leyó, asumió validez, y no verificó. La causa raíz era el
comentario stale, no el código.

---

## Anti-patrones específicos

- **Confiar en el comentario en code review**: el reviewer ve
  `// Alineado con commits X+Y` y asume válido sin hacer `git show`.
- **Propagar el comentario en refactors**: al copiar código, el comentario
  viaja con él y eventualmente se vuelve falso sin que nadie lo note.
- **No actualizar el comentario al revertir el commit citado**: el `git
  revert` no borra comentarios — el comentario sobrevive afirmando
  alineación con un commit que ya no existe en la línea de desarrollo.
- **Usar el comentario como "prueba" en debates técnicos**: "ya está
  alineado con X" cuando el comentario es la única evidencia es razonar
  desde una afirmación no verificada.

---

## Alternativas seguras a los comentarios temporales

Cuando se necesita marcar alineación cross-stack:

| En vez de | Usar |
|-----------|------|
| `// Alineado con commits X+Y` | Test de contrato que valide el shape real en CI |
| `// Refactorizado a v2.3.0` | Versión semántica en el archivo + lock |
| `# Sincronizado con backend` | Tipos generados (OpenAPI codegen, Prisma) |
| `<!-- Coherente con schema X -->` | Validador automatizado en pre-commit |

Si el comentario es la única opción (no hay test/codegen disponible),
incluir **fecha y SHA** explícitos para que la revisión periódica detecte
drift:

```typescript
// Alineado con backend commit 284df74 al 2026-05-22.
// Re-verificar si el endpoint POST /contratos cambia su contrato.
```

---

## Relación con otras reglas

- `~/.claude/rules/verificar-citas-normativas.md § Familia 2` — regla
  global hermana. Esta regla extiende el principio al sub-caso "comentarios
  temporales en código".
- `reglas/arreglar-al-detectar.md` — un comentario stale detectado es
  trabajo a resolver en mismo turno (actualizarlo o eliminarlo).
- `~/.claude/rules/usar-sistema-swl.md` — invocar `revisor-codigo-swl`
  cuando se sospecha drift acumulado de comentarios temporales en un
  módulo.

---

## Checklist al detectar un comentario temporal

- [ ] ¿El comentario afirma alineación con algo verificable (commit, schema, versión)?
- [ ] ¿Verifiqué la fuente real con `grep`/`Read`/`git show` ANTES de actuar?
- [ ] Si hay drift detectado, ¿actualicé/eliminé el comentario en el mismo commit?
- [ ] Si voy a propagar el código (copy-paste, refactor), ¿el comentario sigue siendo válido?
- [ ] Si el comentario es la única opción, ¿incluye fecha y SHA explícitos?
