---
name: proceso-confianza-pre-implementacion
description: >
  Evaluación de confianza pre-implementación con scoring de 5 dimensiones
  (sin duplicación 25%, cumplimiento de arquitectura 25%, docs oficiales 20%,
  referencias OSS 15%, causa raíz identificada 15%) y umbrales 0.9 / 0.7 / <0.7.
  Cargar antes de escribir la primera línea de una feature, refactor o fix no
  trivial — especialmente cuando la tarea cruza >1 archivo o introduce un patrón
  nuevo. Adaptación del patrón ConfidenceChecker de SuperClaude_Framework.
version: "1.0.0"
herramientasPermitidas: [Read, Grep, Glob, Bash]
exclusiones:
  - "No cargar para fixes triviales (typo, rename, comentario) — el overhead supera el valor."
  - "No cargar cuando ya se ejecutó `/swl:discutir-fase` y existe `CONTEXTO.md` con decisiones cerradas — ese flujo ya cubre la verificación previa."
  - "No cargar para tareas exploratorias (`/swl:explorar`, scouting de codebase) donde el objetivo es entender, no implementar."
  - "No cargar para fixes urgentes de producción con incidente activo — aplicar fix mínimo, este protocolo queda para el post-mortem."
evolvable: true
---

# Habilidad: Evaluación de confianza pre-implementación

## Propósito

Detener el "wrong-direction execution" antes de empezar. El costo de implementar
una solución incorrecta supera siempre el costo de la verificación previa: el
material analizado (SuperClaude_Framework `pm_agent/confidence.py`) reporta
ROI **25-250×** en token savings cuando este check detiene una iteración
equivocada. SWL ya tiene la regla `analisis-previo-tareas-grandes.md` con el
espíritu correcto; este skill la operacionaliza con scoring objetivo y umbrales
de acción.

## Cuándo cargar

- Antes de escribir la primera línea de una feature nueva > 50 LOC.
- Antes de un refactor que cruza >1 archivo o >1 módulo.
- Antes de fix de bug donde la causa raíz no está identificada todavía.
- Antes de adoptar una librería externa nueva.
- Cuando el usuario dice "implementa X" sin contexto previo y el agente
  no tiene certeza ≥90% de qué hacer.

## Cuándo NO cargar

Listado en el campo `exclusiones` del frontmatter — incluye fixes triviales,
fases con `CONTEXTO.md` ya cerrado, tareas exploratorias e incidentes
urgentes.

---

## Protocolo de evaluación (5 checks ponderados)

Antes de tocar código, el agente responde estos 5 checks. Cada uno aporta una
porción del score total (0.0 a 1.0).

### Check 1 — Sin duplicación (peso 0.25)

¿Existe ya en el codebase una función, clase, módulo o utilidad que resuelva
el mismo problema?

- Ejecutar `Grep` con palabras clave del nombre tentativo de la nueva entidad.
- Revisar `INVENTARIO.md` para componentes SWL ya registrados.
- Buscar imports/usos que sugieran que ya hay solución.

**Pasa** si la búsqueda confirma que no existe equivalente o el equivalente
está deprecado/marcado para eliminación. **No pasa** si hay duda o si existe
algo que con extensión menor cubriría el caso.

### Check 2 — Cumplimiento de arquitectura (peso 0.25)

¿La solución propuesta usa el stack y los patrones ya definidos del proyecto?

- Leer `CLAUDE.md` del proyecto (sección "Stack" y "Convenciones").
- Revisar ADRs vigentes (`docs/adr/` o `.planning/adrs/`).
- Verificar reglas globales (`~/.claude/rules/`) y del proyecto (`reglas/`).

**Pasa** si la solución se alinea con el stack declarado y no contradice
ningún ADR vigente. **No pasa** si introduce dependencia nueva no justificada,
si rompe una invariante documentada o si elige un patrón distinto al que el
proyecto ya estandariza para el mismo problema.

### Check 3 — Documentación oficial verificada (peso 0.20)

¿Se consultó documentación oficial actualizada de la librería/API/patrón
relevante?

- Para librerías de terceros: regla `usar-context7.md` obliga consultar
  Context7 antes de generar código que las use.
- Para APIs internas: leer el módulo objetivo, no asumir su contrato por
  el nombre.
- Para patrones del framework: documentación oficial vigente (no copiar
  ejemplos de StackOverflow sin verificar versión).

**Pasa** si la doc oficial está leída y la API/patrón coincide con lo
planeado. **No pasa** si se asume la API por memoria del modelo o si la
documentación está desactualizada.

### Check 4 — Referencia OSS funcional (peso 0.15)

¿Existe una implementación open-source madura que resuelva el problema y
se haya consultado?

- Buscar en repos de referencia (`temp/`, `respositorios-git/`, GitHub).
- Si hay implementación OSS validada, su patrón es la base; SWL adapta,
  no reescribe.
- Si no hay OSS de referencia, documentar **por qué** se prefiere solución
  custom.

**Pasa** si se identificó OSS de referencia o se justificó la ausencia.
**No pasa** si simplemente no se buscó.

### Check 5 — Causa raíz identificada (peso 0.15)

Aplicable a bugfixes y refactors motivados por un problema observado.
¿Se identificó la causa raíz con certeza, o se está parchando un síntoma?

- Reproducir el bug en localhost o con test mínimo.
- Aislar la línea/función responsable, no solo el módulo.
- Verificar que la solución elimina la causa, no esconde el síntoma.

**Pasa** si la causa raíz está localizada con archivo:línea o función
específica, sin lenguaje vago ("posiblemente", "creo que", "tal vez").
**No pasa** si hay incertidumbre o si el fix es "agregar try/catch para que
no falle".

Para tareas que no son bugfix (features nuevas, refactors planeados),
este check se da por pasado automáticamente — pero documentar en el
output que "no aplica causa raíz, es trabajo nuevo".

---

## Umbrales y acción recomendada

Tras sumar los pesos de los checks que pasan:

| Score | Nivel | Acción |
|---|---|---|
| **≥ 0.9** | Alta confianza | Proceder con la implementación. La inversión de los checks ya está pagada. |
| **0.7 – 0.89** | Media confianza | **No implementar todavía**. Presentar al usuario las opciones específicas que cierran los gaps. Esperar elección. |
| **< 0.7** | Baja confianza | **DETENERSE**. La investigación está incompleta. Volver a investigar — no implementar bajo este nivel. |

El skill `analisis-previo-tareas-grandes` aplica cuando el score es 0.7-0.89
y la tarea es grande: produce tabla comparativa + 3 opciones para el usuario.

---

## Formato de reporte obligatorio

Antes de cualquier escritura de código, emitir al usuario (o registrar en
`.planning/sessions/`) el siguiente formato:

```
### Confianza pre-implementación

- ✅/❌ Check 1 — Sin duplicación: <descripción de qué se buscó y resultado>
- ✅/❌ Check 2 — Arquitectura: <ADRs/reglas/stack verificados>
- ✅/❌ Check 3 — Docs oficiales: <fuente consultada o "no aplica">
- ✅/❌ Check 4 — Referencia OSS: <repo/módulo de referencia o justificación>
- ✅/❌ Check 5 — Causa raíz: <archivo:línea o "no aplica (trabajo nuevo)">

**Score**: 0.XX
**Nivel**: Alto / Medio / Bajo
**Acción**: <Procedo / Presento opciones / Detengo y re-investigo>
```

El reporte NO es opcional cuando el skill se carga. Si el agente decide
saltarlo "por brevedad", está violando el contrato del skill — y la regla
`debatir-antes-de-aceptar.md` exige justificar la omisión, no esquivarla.

---

## Reglas obligatorias

1. **Score honesto**: no inflar checks "para superar el umbral". Si un check
   no se hizo, marcar ❌. **Por qué**: inflar destruye el ROI del 25-250× —
   un score artificial alto hace que el agente proceda con baja confianza
   real, y el costo de la corrección posterior anula el ahorro.

2. **Reportar antes de implementar**: el reporte se entrega ANTES del primer
   `Write` o `Edit`, no después. **Por qué**: si se reporta después es
   justificación, no verificación.

3. **No saltar checks "porque obvio"**: el Check 1 (duplicación) es el más
   tentador de saltar porque "obvio que no existe". `Grep` es de 2 segundos;
   la duplicación silenciosa cuesta horas (ver `arreglar-al-detectar.md`).

4. **Lenguaje específico, no vago**: cuando se marca ✅ un check, decir QUÉ
   se verificó. "Grep en `backend/auth/` con patrón `verifyToken` — 0
   resultados" es válido. "Revisé que no existe" no.

5. **Si el usuario insiste en proceder con score bajo**, la regla
   `debatir-antes-de-aceptar.md` aplica: presentar el costo conocido,
   esperar confirmación informada, registrar la excepción en la sesión.
   No proceder silenciosamente.

---

## Relación con otras herramientas SWL

- **Skill `analisis-previo-tareas-grandes` (regla global)**: cubre el caso
  específico de tarea grande con score 0.7-0.89. Produce tabla comparativa
  y 3 opciones. Este skill (confianza pre-implementación) es más general:
  cubre cualquier tarea no trivial.
- **Skill `proceso-autoverificacion-evidencias`**: aplica al CIERRE del
  trabajo (post-implementación), con las Four Questions. Este skill aplica
  al INICIO.
- **Skill `discutir-fase`**: cuando hay HOJA-RUTA.md y CONTEXTO.md formal,
  ese flujo absorbe el rol de este skill — no cargar ambos.
- **Regla `verificar-citas-normativas.md`**: aplica a citas verificables
  durante el trabajo. Este skill aplica al inicio del trabajo.
- **Skill `confidence-check` (oficial SuperClaude)**: si SuperClaude está
  instalado en el sistema, el skill oficial coexiste. Este skill SWL es
  la versión integrada con el resto del flujo SWL (CONTEXTO.md, ADRs,
  `_userland/`, `arreglar-al-detectar.md`). Preferir el SWL dentro de
  proyectos SWL.

---

## Ejemplo de uso

Usuario: *"implementa un endpoint POST /facturas/cancelar"*.

Agente carga este skill antes del primer `Write`:

```
### Confianza pre-implementación

- ✅ Check 1 — Sin duplicación: Grep "cancelar.*factura" en backend/app/ → 0 resultados.
  No existe endpoint equivalente. INVENTARIO.md confirma sin overlap.
- ✅ Check 2 — Arquitectura: CLAUDE.md confirma FastAPI + SQLAlchemy async.
  ADR-0008 establece convención de endpoints "/recursos/accion" para
  acciones que no mapean a CRUD. Esta solución cumple.
- ✅ Check 3 — Docs oficiales: leí docs/endpoints-existentes/facturas.md;
  el modelo Factura ya tiene método `puede_cancelarse()`.
- ❌ Check 4 — Referencia OSS: no busqué; es lógica de negocio interna.
  Justificación: no aplica patrón OSS estándar — es flujo del dominio.
- ✅ Check 5 — Causa raíz: no aplica (trabajo nuevo, no bugfix).

**Score**: 0.85 (5×0.25+0.20+0+0.15 = pasan 4 de 5, falla Check 4
con justificación aceptable)
**Nivel**: Medio (0.7-0.89)
**Acción**: Presento opciones al usuario antes de implementar.

¿Procedo con la implementación directa, o prefieres que valide primero
con un test de aceptación escrito (TDD)?
```

El usuario decide, no el agente. Score medio → preguntar.
