DETENTE. LEE ESTE SKILL.MD COMPLETO ANTES DE LLAMAR A CUALQUIER ENDPOINT.
¿Qué hace assess?
Da un paso atrás y reevalúa críticamente el estado del proyecto. Proporciona guía interactiva (con intervención humana) y análisis programático (pipelines automatizados). Especializado en poda de documentación y alineación doc-código.
Uso desde CLI
# Evaluación JSON estructurada para pipelines
.pi/skills/assess/assess.py run . --output assessment.json
# Generar todas las figuras a partir de la evaluación
create-figure from-assess --input assessment.json --output-dir ./figures/
Flujo de Evaluación
1. Definir el Alcance
Alcance claro ("evalúa el módulo de autenticación") → proceder directamente. Alcance abierto ("dar un paso atrás") → preguntar: ¿inquietudes? ¿calidad del código vs documentación? ¿problemas conocidos que omitir? Poda de documentación ("podar documentación") → preguntar: ¿funcionalidades obsoletas? ¿documentación faltante? ¿alineación?
2. Encontrar la Raíz del Proyecto y Detectar el Ecosistema
Detectar mediante archivos marcadores (pyproject.toml, package.json, Cargo.toml, go.mod). Leer metadatos específicos del ecosistema, luego documentación universal (README.md, CONTEXT.md, AGENTS.md).
3. Cargar el Manifiesto del Skill (Con Filtro de Ruta)
Cargar .pi/skills-manifest.json para evaluaciones que puedan conducir a recomendaciones del tipo "deberíamos construir X". Omitir para revisiones de estado y solo documentación.
cat .pi/skills-manifest.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'Skills: {data[\"skill_count\"]} (generado: {data[\"generated\"]})')
"
Advertir si el manifiesto tiene más de 7 días de antigüedad. Alternativa: ls .pi/skills/ | wc -l.
4. Escaneo Rápido → Confirmación → Análisis Profundo
- Leer metadatos del proyecto, README, y escanear la estructura global
- Anotar 2-3 observaciones iniciales, confirmar con el usuario
- Análisis profundo según la guía del usuario — para cada hallazgo: ¿bloqueante? ¿conocido? ¿complejidad de la corrección?
5. Informe Colaborativo
Presentar los hallazgos y preguntar cuáles corregir. Ofrecer /create-figure para visualización.
Categorías de Evaluación
1. Alineación Doc-Código
- Afirmaciones del README vs implementación
- Validación de referencias cruzadas (enlaces internos, ejemplos de código)
- Marcadores de marcador de posición e información desactualizada
- Deprecación: documentación para funcionalidades eliminadas
2. Aspiracional vs Implementado
- Stubs (
pass,raise NotImplementedError), notas de marcador de posición - Funcionalidades en la estructura del código pero sin lógica, dependencias no utilizadas
3. Código Frágil
- Valores hardcodeados, manejo de errores faltante, expresiones regulares/parsing frágiles
4. Código que no Funciona
- Rutas de código muertas, supresión silenciosa de excepciones, integraciones rotas
5. Código Sobreingenierizado
- Abstracciones con implementación única, configuración para flexibilidad hipotética
6. Cobertura de Pruebas (No Negociable)
Revisar cada funcionalidad/módulo para archivos de prueba, pruebas que pasan, casos límite.
Señalar pytest.mark.skip sin razón, "0 pruebas recolectadas", pruebas que no afirman nada.
Auditoría de archivos de tarea: Verificar que cada tarea tenga una Definición de Hecho con prueba/afirmación específica. Bloquear la ejecución si las tareas de implementación carecen de Definición de Hecho.
7. Funcionando Bien
Reconocer código sólido para calibrar la evaluación.
Formato de Salida
# Evaluación: <nombre-del-proyecto>
## Resumen
<2-3 oraciones: salud general, hallazgos clave>
## Hallazgos
### Alineación Doc-Código
| Afirmación | Realidad | ¿Acción? |
### Problemas Encontrados
1. **archivo.py:123** - [Problema] — Gravedad: A/M/B — Corrección sugerida: [breve]
### Cobertura de Pruebas
| Funcionalidad | Estado de Prueba | Acción Necesaria |
### Funcionando Bien
- [Código sólido a reconocer]
## Próximos Pasos Recomendados
1-4 acciones priorizadas. Preguntar cuál comenzar.
Políticas
- Solo lectura por defecto — nunca escribir archivos sin consentimiento explícito
- Imprimir primero, escribir con consentimiento — mostrar el contenido propuesto, luego ofrecer escribirlo
- Colaborar — la evaluación es diálogo, no monólogo
- Preguntar antes de ejecutar — obtener permiso antes de pruebas, builds, servicios de pago
- Escalar sabiamente — sugerir
/review-codepara problemas complejos/críticos - Ser específico — rutas de archivo y números de línea
- Ser procesable — cada hallazgo sugiere próximos pasos
- La cobertura de pruebas es no negociable — señalar pruebas faltantes como bloqueantes
Investigación Externa
Disponible cuando sea necesario (preguntar antes de servicios de pago):
/context7— documentación de librerías (gratuito)/brave-search— web general (gratuito)/perplexity— investigación profunda (de pago)
Errores Comunes
# MAL: Tratar todos los hallazgos de la evaluación como bloqueantes
# → El agente añade docstrings a 12 helpers privados. Inflación innecesaria.
# BIEN: Revisar hallazgos con el usuario. Escalar problemas complejos a /review-code.
# MAL: Saltar /assess después de cambios importantes
# → Los ejemplos del README usan una firma de función antigua. Los usuarios encuentran errores.
# BIEN: Ejecutar assess --focus "doc-code-alignment" después de editar APIs principales
# MAL: Ejecutar /assess y actuar sobre resultados desactualizados
# → La evaluación tiene 3 días de antigüedad. El código ha cambiado desde entonces.
# BIEN: Siempre volver a ejecutar assess; nunca almacenar en caché resultados entre sesiones