ritamgh/claude-skills

Contrato de Evidencia

Crea planes que sean comprobables y estén fundamentados en el repositorio real, no en conjeturas plausibles.

Activación

Aplica esta skill automáticamente cuando la tarea requiera un plan de implementación no trivial o una revisión de plan. No esperes a que el usuario la invoque explícitamente.

Omite el contrato completo para cambios triviales donde el objetivo, el comportamiento y la verificación ya sean obvios. Indica la comprobación simple en su lugar.

Esta skill es solo de planificación. No edites archivos de implementación a menos que el usuario también te haya pedido ejecutar el plan.

Flujo de trabajo

1. Establecer intención y éxito

Reformula el resultado deseado en una oración. Extrae el comportamiento de aceptación concreto de la solicitud. Si la redacción es ambigua, investiga el repositorio antes de preguntar al usuario. Pregunta solo cuando, tras la investigación, sigan siendo posibles resultados materialmente diferentes.

2. Recopilar evidencia mínima suficiente

Antes de proponer arquitectura o nombrar archivos afectados:

1. Lee PROJECT_CONTEXT.md cuando exista.
2. Localiza los puntos de entrada de la funcionalidad con una búsqueda dirigida.
3. Lee el conjunto más pequeño de archivos de implementación, configuración y pruebas relevantes.
4. Rastrea llamadores importantes, dependencias, límites de persistencia e interfaces públicas.
5. Registra contradicciones entre la documentación y el código. Trata el código y el comportamiento ejecutable como evidencia más sólida.

Evita escaneos amplios del repositorio cuando la evidencia dirigida sea suficiente.

3. Clasificar cada afirmación material

Usa estas etiquetas internamente y exponlas cuando sea útil:

• Observado: respaldado directamente por un archivo, símbolo, resultado de comando, prueba u observación en tiempo de ejecución.
• Inferido: fuertemente implicado por evidencia observada pero no demostrado directamente.
• Desconocido: información material que no se ha establecido.

Nunca presentes una afirmación inferida o desconocida como un hecho. Incluye una ubicación de código o una observación de herramienta para afirmaciones observadas importantes. No inventes rutas de archivo, APIs, dependencias o comportamientos existentes.

4. Resolver incógnitas bloqueantes

Investiga las incógnitas que podrían cambiar la arquitectura, el alcance, el flujo de datos, la compatibilidad o el comportamiento de aceptación. Si una incógnita no se puede resolver localmente:

• indícala explícitamente,
• explica por qué es importante,
• propón la suposición acotada más segura, y
• pregunta al usuario solo si proceder podría producir el resultado incorrecto.

5. Producir un plan con puerta de evidencia

Cada punto del plan no trivial debe incluir:

1. Cambio: el paso de implementación coherente más pequeño.
2. Evidencia: hechos observados del repositorio que justifican el paso, con rutas o símbolos relevantes.
3. Superficie afectada: archivos, interfaces, datos, llamadores, dependencias o flujos de trabajo que probablemente cambien.
4. Verificación: una prueba ejecutable, compilación, lint, tiempo de ejecución u observación de aceptación.
5. Riesgo o suposición: solo cuando sea material, etiquetado como inferido o desconocido.

Prefiere planes que mapeen un requisito a una comprobación observable. Incluye cobertura de regresión para correcciones de errores y cambios sensibles a la compatibilidad.

6. Ejecutar la puerta de planificación

Antes de presentar el plan, verifica:

• Cada resultado solicitado se asigna al menos a un punto del plan.
• Cada punto del plan tiene evidencia y una verificación concreta.
• Los archivos y símbolos nombrados fueron observados, no adivinados.
• Las suposiciones materiales son visibles y están clasificadas.
• Las dependencias y los límites de integración están cubiertos.
• El plan utiliza el cambio más pequeño que satisface la solicitud.
• No se agregaron características especulativas ni refactorizaciones no relacionadas.

Si la puerta falla, investiga o revisa el plan antes de devolverlo.

Formato de salida

Mantén el resultado conciso a menos que la tarea sea compleja.

## Contrato de evidencia
- Observado: `ruta/al/archivo` establece ...
- Inferido: ... porque ...
- Desconocido: ...; suposición acotada o decisión requerida ...

## Plan
1. **Cambio** ...
   - Evidencia: ...
   - Afectado: ...
   - Verificar: ...
   - Riesgo/suposición: ...

## Puerta de finalización
- [ ] La correspondencia requisito-verificación está completa
- [ ] No quedan suposiciones sin etiquetar
- [ ] Las comprobaciones de aceptación son ejecutables

Omite las secciones vacías de inferido o desconocido. Para planes pequeños, comprime cada punto en una sola línea manteniendo la evidencia y la verificación.

Anti-patrones

No hagas:

• elaborar un plan solo a partir de nombres de archivo,
• usar "probablemente", "posiblemente" o "debería" sin marcar una inferencia,
• afirmar que las pruebas pasan sin ejecutarlas,
• sustituir una verificación simulada por una ruta de aceptación real disponible,
• cargar al usuario con preguntas que se pueden responder desde el repositorio,
• convertir el contrato en trámites burocráticos para cambios triviales,
• comenzar la implementación solo porque el plan está completo.