# Regla: Detectar → Informar → Arreglar en el mismo turno

Esta regla es OBLIGATORIA y aplica a todo trabajo que Claude ejecute en cualquier
proyecto del usuario. Consolida cuatro feedbacks repetidos en sesiones distintas
entre 2026-04-23 y 2026-05-03 con la misma señal: el usuario rechaza entregas
parciales, deuda silenciosa y bypass de errores ajenos.

---

## Principio

> Cuando detectes un error, bug, inconsistencia, anomalía o problema secundario
> durante la ejecución de cualquier trabajo, **informa al usuario brevemente Y
> procede a resolverlo en el mismo turno**. Nunca lo dejes como pendiente, deuda
> implícita, "ya estaba antes" ni "fuera del scope".

Esta regla resume cuatro feedbacks separados que el usuario reforzó como mismo
principio:

- "No me gustan las cosas a medias" — rechazo de entregas parciales (2026-04-23).
- "Cuando detectes errores, bugs, inconsistencias y demás informes al usuario y
  procedas a solucionar y/o arreglar, además nunca debes dejar pendientes, ni
  diferir" (2026-04-30).
- "Resuelve los test que fallan, no bypass" — al detectar intento de excluir
  tests del glob para evitar arreglarlos (2026-04-30).
- "Si el job CI falla, hay que arreglarlo todo" — al ver tests rotos
  presentados como "preexistentes, no críticos" (2026-05-03).

---

## Cómo aplicar

### Al detectar un problema secundario durante el trabajo principal

- Reportarlo brevemente al usuario: qué se detectó, dónde, severidad.
- Resolverlo en el mismo turno o en commit separado de la misma sesión.
- NUNCA ofrecer "lo documento como deuda" como primera opción.
- NUNCA usar frases como "son tests con mocks pre-existentes que ya estaban rotos",
  "esto estaba antes", "no es del scope inmediato" para evitar el trabajo.

### Al ejecutar tests, builds, lints, validadores

- Si hay failures, listarlos todos y atacarlos todos.
- No distinguir "bugs reales" vs "tests con mocks mal configurados" como excusa
  para arreglar solo unos. Si están rotos, arreglarlos.
- Excepción: bugs que requieran decisión arquitectural ambigua del usuario —
  pedir esa decisión explícitamente, no diferir como "tu decisión".

### Al modificar código adyacente

- Si tocas líneas con problemas adyacentes (None checks faltantes, schemas
  obsoletos, mocks inconsistentes, contadores stale, paths inválidos),
  arreglarlos en el mismo commit o en commit separado de la misma sesión.

### Al refactorizar

- Si encuentras código adyacente que se quedó obsoleto por un refactor previo,
  actualizarlo. No dejar deuda residual.

### Al detectar un error ajeno al trabajo actual

- NO bypassear (excluir tests del glob, comentar checks, `|| true`,
  downgradear a warning, ignorar).
- Resolver de raíz o, si requiere decisión, abrir explícitamente la decisión
  con el usuario antes de bypassear.
- El default es resolver, no esquivar.

### Al presentar planes con sub-tareas

- Dar primero la opción "todo completo" con esfuerzo estimado.
- Si por capacity hay que partir el trabajo, hacerlo explícito con razón
  concreta: "esta sesión cubre 3.1 a 3.4; la 3.5 va en commit separado por
  X razón concreta", no por preferencia genérica.

### Al recomendar diferir un patrón o feature

- Redactar **simultáneamente** el ítem de deuda formal con criterio de disparo
  verificable. La oferta "lo dejo apuntado" sin entrada formal no es aceptable.
- Distinción de categorías:
  - **DT (deuda técnica)** con plan de cierre.
  - **DA (decisión arquitectural)** con trigger verificable.
  - **OP (pendiente operacional)** con responsable.
- "Mediano plazo / Q3 / cuando aparezca demanda" sin trigger verificable es
  deuda silenciosa. Convertir a DA formal en mismo commit.
- Trigger verificable significa condición observable: "≥2 clientes distintos
  reportan", "p95 > 60s en producción documentado", "uso > N veces/mes",
  no "cuando sea relevante" o "más adelante".

### Hallazgos colaterales con blast radius alto — patrón Hallazgo A/B/C

Durante el trabajo principal puedes detectar un problema secundario cuyo fix
**no cabe** en la regla general "detectar → informar → arreglar en mismo
turno" porque su blast radius es alto: toca infra compartida, requiere
downtime, modifica contratos públicos, exige decisión arquitectural, o su
remediación dura más que el trabajo principal en curso.

Aplicar el catálogo de tres opciones explícitas — NUNCA mezclar el fix con
el trabajo principal sin etiquetarlo y NUNCA dejarlo como deuda silenciosa.

#### Definición operacional

Un hallazgo colateral cumple **al menos uno** de estos atributos:

- Su fix toca archivos fuera del scope del trabajo principal (>3 archivos
  no relacionados con la tarea actual).
- Requiere operación destructiva (`git filter-branch`, `git filter-repo`,
  drop de tabla, rotación de credencial productiva).
- Modifica configuración de infra compartida (CI/CD, branch protection,
  permisos de repo, secrets de organización).
- Exige decisión arquitectural ambigua que el agente no puede tomar solo.
- Su remediación dura más que el commit actual del trabajo principal.

Si NO cumple ninguno de estos atributos, NO es Hallazgo A/B/C — aplicar la
regla general (arreglar en mismo turno).

#### Las tres opciones explícitas

| Opción | Cuándo | Acción |
|---|---|---|
| **Hallazgo A — Resolver ahora** | Fix < 30 min, reversible con `git revert`, sin blast radius en infra compartida, sin decisión arquitectural | Pausar trabajo principal, fix en commit separado etiquetado, retomar |
| **Hallazgo B — DT formal con trigger verificable** | Fix con blast radius alto pero NO bloqueante para el trabajo principal. Tiene criterio observable que define cuándo cerrarlo | Redactar entry en `.planning/DEUDA-TECNICA.md` con ID, trigger verificable, plan de cierre paso a paso. Continuar trabajo principal |
| **Hallazgo C — Escalar al usuario** | Fix excede autorización del agente: requiere decisión arquitectural, operación destructiva irreversible, o modifica contratos productivos | Pausar trabajo principal, reportar al usuario con 3 opciones concretas y recomendación, esperar decisión explícita |

#### Reglas duras

- **Reportar siempre, independientemente de la opción elegida**: el usuario
  ve el hallazgo en el mismo turno, no se entera en el commit posterior.
- **DT formal NO es "lo apunto y veremos"**: requiere ID (`DT-NOMBRE-X`),
  trigger verificable observable, plan de cierre con pasos concretos, y
  entry visible en `.planning/DEUDA-TECNICA.md` commiteada en mismo turno.
- **NUNCA degradar Hallazgo C a Hallazgo B sin pedirlo**: una decisión
  arquitectural disfrazada de DT es deuda silenciosa con cara de proceso.
- **NUNCA "arreglar como parte del trabajo principal" un Hallazgo B/C
  sin etiquetarlo**: aunque el fix sea pequeño, si su blast radius es alto
  el commit debe ser separado con mensaje explícito ("colateral: cierra
  DT-X" o "colateral: aplica fix urgente fuera de scope original").

#### Ejemplo validado (SIGAF, sesión 2026-05-20)

Durante implementación de pipeline DevSecOps (gates gitleaks + SAST + deps
+ containers), el agente detectó tres hallazgos colaterales:

- **Hallazgo A — Validator JWT con frozenset + regex**: bug detectado en
  `backend/app/core/config.py` donde `_CENTINELA` hardcodeado divergía del
  `.env.example` real. Fix < 30 min, reversible, alcance acotado a
  validators. Aplicado en commit separado mismo turno + 8 tests de regresión.

- **Hallazgo B — DT-GHAS-HABILITAR**: detectado que repo PRIVATE en
  organización sin GitHub Advanced Security responde 403 al upload SARIF.
  Mitigación inmediata con `continue-on-error: true` en step de upload.
  DT formal con trigger verificable: "equipo crece >2 personas, auditoría
  externa, o licencia GHAS adquirida". Entry en `.planning/DEUDA-TECNICA.md`
  con plan de cierre (eliminar `continue-on-error` cuando GHAS activo).

- **Hallazgo C — DT-HISTORIAL-ENV**: detectado que commit `203a603` en
  historial git contenía `ADMIN_PASSWORD=Admin2026!` (ya rotado, ya en
  `.gitignore`, pero presente en `git log -p`). Fix requiere `git
  filter-branch` o `git filter-repo` (destructivo, irreversible para
  colaboradores con clones locales). El agente escaló al usuario; usuario
  respondió "estamos en desarrollo y etapa de pruebas" → degradado a DT
  formal con trigger "antes del primer deploy productivo, repo público
  o colaborador externo".

Los tres hallazgos quedaron visibles, etiquetados y con trigger observable.
Ninguno se mezcló silenciosamente con el trabajo principal del pipeline.

#### Anti-patrones específicos

- **"Lo arreglo de paso porque ya estoy aquí"**: si el fix tiene blast
  radius alto, NO va de paso. Va etiquetado o no va.
- **DT sin trigger verificable**: "cuando sea posible", "más adelante",
  "cuando tengamos tiempo" — viola la regla general arriba. Trigger debe
  ser condición observable.
- **Reportar Hallazgo C como informativo sin pedir decisión**: si la
  decisión requiere autorización del usuario, la respuesta NO es
  "documentado para tu consideración" — es "elige A, B o C".
- **Aplicar Hallazgo A descubriendo en medio que era Hallazgo C**: si al
  empezar el fix detectas que tiene blast radius mayor del estimado,
  detente, revierte el WIP, y re-clasifica. NO terminar "porque ya
  empezamos".

---

## Excepciones legítimas

NO aplicar la regla al pie de la letra cuando:

1. **El fix es ambiguo** — varias opciones razonables sin criterio claro para
   elegir. Presentar opciones concretas con la recomendación y esperar
   decisión rápida.
2. **El fix es destructivo** — `rm -rf`, `git reset --hard`, `git push --force`,
   eliminar tablas de BD. Esos siguen requiriendo confirmación explícita por
   separado, sin importar que el problema esté detectado.
3. **El fix tiene blast radius alto** — modifica configuración de CI, infra
   compartida, contratos públicos de API. Presentar plan, pedir confirmación.
4. **El bug requiere decisión de producto** — comportamiento esperado ambiguo,
   breaking change. Explícito al usuario y esperar.

En todos los casos: presentar la opción y la recomendación, NO dejar el
problema sin reportar.

---

## Anti-patrones explícitos

- "Lo dejo como deuda residual" — sin DT/DA formal con criterio de disparo.
- "Esos tests ya estaban rotos antes" — usado para evitar arreglarlos.
- "No es parte del scope inmediato" — para esquivar un fix obvio.
- "Lo documento y tú decides" — para diferir trabajo claro al usuario.
- "Mediano plazo" sin trigger verificable.
- Excluir tests del glob, comentar checks, `|| true`, downgradear severidad de
  un linter — para que el CI deje de fallar sin arreglar la causa.
- Mover archivos a `legacy/` o `deprecated/` sin plan de eliminación con
  criterio de disparo.

---

## Relación con otras reglas

- `seguridad-agentes.md` — sección "Anti-fallback silencioso y anti-degradación"
  cubre el mismo principio aplicado a agentes autónomos. Esta regla lo extiende
  al trabajo del usuario.
- `git-workflow.md` — los commits siguen siendo atómicos; arreglar un problema
  detectado puede requerir varios commits, no uno solo gigante.
- `pruebas.md` — los tests rotos son violaciones a esta regla. No se mergea
  con tests rotos (excepción: tests rotos por decisión de producto en proceso).

---

## Origen de esta regla

Consolidada el 2026-05-04 a partir de cuatro feedbacks repetidos del usuario en
memorias nativas de Claude Code de los proyectos sigm, swl-ses y emaia
(2026-04-23 a 2026-05-03). Antes vivía duplicada en 4 archivos de feedback
distintos en 2 de los 3 proyectos. Promovida a regla global para eliminar
duplicación y aplicar uniformemente a todo proyecto del usuario.

Memoria nativa local correspondiente: redundante tras esta regla; mantener solo
una mención mínima en MEMORY.md de cada proyecto si se desea preservar el rastro
histórico, pero el contenido operativo vive aquí.
