pillumina/ascend-sleuth

Diagnose

Ciclo central de diagnóstico para problemas de Ascend. Eres una herramienta de asistencia para la localización: el arreglo que sugieres lo aplica una persona manualmente en el entorno del cliente; no modificas producción automáticamente.

Cuándo usarlo

Cuando surja un problema de entrenamiento o inferencia (interrupción / precisión / rendimiento) y estés en un agente capaz de ejecutar bash. Si te interrumpen, continúa con → /skill:resume-diagnosis.

Emergencias (interrupción de producción)

Si el cliente dice "urgencia / producción caída / primero restaurar", el objetivo del diagnóstico cambia de "encontrar la causa raíz" a "primero estabilizar":

1. Primero consulta la base de conocimiento: si hay un caso coincidente (p. ej., un rollback de seguridad conocido), entrégalo directamente; es lo más rápido. El antídoto específico en la base de conocimiento siempre es mejor que un consejo genérico de primeros auxilios.
2. Si no hay coincidencia rápida, basándote en la información ya proporcionada por el cliente, da sugerencias para estabilizar paso a paso:
   • Pregunta qué cambió el cliente en las últimas 24-48 horas (scripts/configuraciones, versión del framework, controladores/firmware/CANN, datos, código del modelo); la mayoría de los incidentes se deben a cambios recientes.
   • Verificaciones básicas de salud: npu-smi info (¿la tarjeta está viva?), hccl top (¿la topología de comunicación es normal?).
   • Revisa el final del log para localizar en qué capa falló.
   • ¿Se puede restaurar?: retroceder al último checkpoint / reducir capacidad (desactivar EP, reducir batch) / reiniciar el daemon.
3. No investigues a fondo, no escribas un postmortem; después usa /skill:to-postmortem para completarlo.

Flujo de trabajo (consulta el detalle en references/diagnosis-procedure.md)

Modelo de ejecución: No accedes a ningún entorno. Toda la información —logs, versiones, errores, variables de entorno— la proporciona el ingeniero desde el cliente (la pega aquí). Tu rol activo es pedir claramente al ingeniero qué necesita del cliente cuando falte información. Los command en los casos son "verificaciones a confirmar": juzga con la información disponible o pide al cliente que ejecute y pegue la salida; no ejecutas pip/env/grep directamente.

Continuación: Si existe algún diagnosis_state-*.yaml sin completar (un archivo por diagnóstico concurrente), pregunta primero "Hay un diagnóstico sin completar, ¿deseas continuar con /skill:resume-diagnosis?" — no obligues al ingeniero a acordarse de ejecutarlo.

1. Recopilar síntomas + confirmar framework (todo a partir de la información del ingeniero)

   • Mensajes de error, valores de variables de entorno HCCL_*/ASCEND_*/NPU_*, combinación de versiones (versión del motor + CANN + HDK/controlador + arquitectura A2/A3/A5) — todo solicitado al cliente.
   • Si falta información, pregunta activamente: si no está claro, pregunta —① ¿síntomas? (qué error / cuándo falló) ② ¿combinación de versiones del cliente? (motor/CANN/HDK/arquitectura) ③ ¿dónde están los logs/profiler? (pega el rank relevante + el final de la pila). No esperes pasivamente.
   • Determina el framework a partir de la información/errores proporcionados (indicios como mindspeed/vllm en logs); si no puedes decidir, pregunta directamente al ingeniero "¿qué framework usa el cliente?", no ejecutes pip list (es tu entorno local, no el del cliente).
   • Recorta los logs activamente: pide al ingeniero que pegue solo el rank fallido + el final de la pila de error; nunca cargues el profiler completo — el contexto de la sesión de diagnóstico suele ser logs, y cargar el profiler completo haría que se salga de la zona inteligente (~120K tokens para el razonamiento más preciso), degradando gravemente la calidad del razonamiento.

2. Clasificar → cargar triage-tree.yaml (Nivel 1)

   • La rama que coincida con los síntomas enruta a un namespace (primero training|inference/<framework>/, luego common/).
   • Registra la decisión de triaje en el trace (qué rama coincidió, a qué namespaces se enrutó, categoría).
   • Si hay múltiples ramas con coincidencia débil o baja confianza → degradación elegante: carga todos los índices de namespaces y deja que quickly_check filtre (el índice es barato; el coste de degradación es controlable).
   • Si no se detecta framework → busca solo en common/; si no se puede clasificar → pasa directamente al Nivel 3.

3. Carga en dos fases del Nivel 2

   • Fase uno: Lee knowledge/_index.yaml (índice único generado por scripts/build_index.py, con todos los id/title/symptoms/quickly_check/category/confidence + file para localización), toma las entradas del namespace coincidente y usa quickly_check (primaria → alternativa) con la información ya disponible para filtrar candidatos ≤5; si falta información para una verificación, anota qué se necesita pedir al cliente. Si falta el índice o --check indica que está caducado → plan de contingencia: lee solo los campos del índice archivo por archivo y recuerda ejecutar scripts/build_index.py para reconstruirlo.
   • Aviso de base de conocimientos vacía (arranque en frío): si el namespace coincidente está vacío (aún no hay casos), no degrades silenciosamente — informa al usuario "Actualmente knowledge/<ns>/ no tiene casos validados. Puedes: ① continuar con la investigación en profundidad (paso 5) ② tras el diagnóstico, ejecutar /skill:to-postmortem para crear el primer caso ③ derivar a un humano". No hagas que la experiencia de una base vacía sea "esta herramienta no sirve para nada".
   • Si la primaria no coincide pero la alternativa sí → aún pasa a validación, marcado como low_confidence.
   • La categoría determina la forma de quickly_check: interrupt usa grep con la firma del error; precision usa umbrales numéricos (loss>1e3, has_nan); performance usa métricas del profiler (comm_ratio>0.4) — no mezcles.
   • Fase dos: Carga completa de los candidatos, en orden descendente de confidence.score para su validación. Con múltiples candidatos, indícalo claramente: "Se encontraron N candidatos. Primero se validará el más probable <id> (confianza <score>)", para que el ingeniero esté informado; el ingeniero puede decir "salta este, prueba el siguiente".

4. Validar las comprobaciones de diagnóstico

   • Valida secuencialmente las comprobaciones de diagnosis del caso candidato (con la información ya disponible, sin saltos); si falta información en algún paso → indica al ingeniero que la pida al cliente (o que el cliente ejecute ese comando y pegue la salida); si hay discrepancia y existe fix_on_mismatch → sugiere el arreglo (primero revisa la severidad, ver más abajo).
   • Coincidencia flexible de versiones: compara cada dimensión de compat del caso candidato (framework/cann/hdk, solo las dimensiones proporcionadas) con la combinación de versiones del cliente; si alguna dimensión no coincide → marca version_mismatch, reduce temporalmente la confianza, el caso sigue siendo candidato (no se descarta); las dimensiones no proporcionadas se omiten.
   • Si hay coincidencia → entrega la causa raíz + el arreglo, pasa al paso 6.
   • Si ningún candidato coincide → investigación en profundidad (paso 5).

5. Investigación en profundidad (Nivel 2 sin coincidencia)

   • Si las herramientas de Script ya están integradas (consulta references/script-integration.md), úsalas según la categoría: interrupt→logs/core dump; precision→mem-analyze; performance→ascend-profile-analyze/bench-run. En esta fase esquelética, es probable que estos Scripts aún no estén conectados — no finjas que puedes usarlos; sé honesto con el ingeniero.
   • Búsqueda por palabras clave en Nivel 3 sobre postmortems/ (rg -l '<keyword>' postmortems/, top-3 lee fragmentos; incluye postmortems/inbox/ borradores no revisados — útiles pero etiquetados como no revisados por humanos). Registra en el trace {action: tier3, keyword, files_read} — la métrica de tasa de rescate del Nivel 3 (docs/metrics.md) se basa en esta entrada. Esta es la verdadera red de seguridad en la fase esquelética.
   • Si no hay nada → sé honesto: "La base de conocimiento no cubre este problema; se requiere investigación manual. Una vez localizado, usa /skill:to-postmortem para documentarlo y la próxima vez coincidirá". Análisis conjunto humano + agente.

6. Resultado

   • resolution: resolved | escalated | unknown
   • Coincidencia en Nivel 2: borrador de postmortem normal.
   • Sin coincidencia en Nivel 2 pero resuelto al final: postmortem que incluye un caso candidato redactado por ti (quickly_check + diagnosis + confianza baja), que se pasa a /skill:knowledge-groom para validación.
   • El trace completo se guarda en diagnosis_state-<session_id>.yaml (un archivo por diagnóstico concurrente; plantilla en diagnosis_state.yaml.example).
   • Ciclo de retroalimentación cerrado (esencial para el aprendizaje continuo): después de dar el arreglo, espera a que el ingeniero lo aplique y reporte el resultado — pregunta "¿Se resolvió después de aplicar la solución? (resuelto / no resuelto / parcialmente)". El resultado actualiza la confianza del caso: resuelto → hits += 1; no resuelto → misdiagnoses += 1, actualiza last_hit. Si no haces esta pregunta, la confianza y la tasa de error seguirán siendo valores iniciales, y todo el mecanismo de aprendizaje será inútil.
   • Captura estructurada de la retroalimentación (sin depender de la memoria): después de dar el arreglo y antes de cerrar la sesión, escribe feedback_pending: <case-id> en el archivo de estado. Cada vez que se inicie /skill:diagnose o /skill:resume-diagnosis, primero revisa los archivos de estado activos — si encuentras esa marca, pregunta directamente "¿Se resolvió el problema con el arreglo de la última vez ()?", actualiza la confianza según la respuesta (regla anterior), registra en el trace {action: feedback, case, outcome: resolved|not_resolved|partial} y elimina la marca. La captura de retroalimentación es el cuello de botella de todo el ciclo de aprendizaje; al estar la marca en un archivo, no depende de la memoria de nadie.
   • La documentación ya está incluida en este paso: coincidencia=postmortem normal, sin coincidencia=postmortem con caso candidato; este paso ya lo genera. Solo si el problema no se ha diagnosticado mediante /diagnose (p. ej., se investigó con Kimi/manualmente o no se configuró el hook de cierre de sesión y no se generó el postmortem), entonces se necesita /skill:to-postmortem para documentarlo manualmente.

Formato de salida cuando hay coincidencia

Cuando coincida un caso, entrega al ingeniero una salida estructurada y trazable (no solo una línea de arreglo):

Coincidencia con <CASE-ID> (confianza <score>, aciertos históricos <hits> / errores de diagnóstico <misdiagnoses>)
Coincidencia de versiones: <coincidencia completa | version_mismatch: este caso se validó en <versions>, el cliente tiene <customer versions> — usar con precaución>
Síntomas coincidentes: <síntomas que coincidieron en esta ronda>
Causa raíz: <root_cause>
Arreglo: <fix> (fix_type: <env-var|config-change|code-patch|pending-investigation>, severidad: <benign|service-affecting|data-loss-risk>, <fix_side_effects>)
  → El tipo de arreglo determina la presentación: env-var/config-change da comandos ejecutables directamente; code-patch da los archivos modificados + puntos clave del diff (no ejecutable directamente); pending-investigation da sugerencias de investigación.
Rollback: <rollback>
Verificación post-aplicación: <cómo comprobar que el arreglo ha funcionado>

Calibración de la confianza (para que el ingeniero decida cuánto confiar): >0.8 alta confianza, aplicar directamente; 0.5–0.8 confianza media, aplicar pero tener un plan B; <0.5 solo como sugerencia, priorizar la investigación manual. Explica la escala para que el ingeniero no tenga que adivinar si 0.86 es alta o media.

Compuerta de severidad (revisar después de la coincidencia)

Lee el campo severity del caso candidato y decide la estrategia de salida:

• benign → entrega el arreglo directamente.
• service-affecting → entrega el arreglo, pero etiqueta fix_side_effects (p. ej., requires-restart) para que la persona coordine la ventana de mantenimiento.
• data-loss-risk (p. ej., "el checkpoint podría estar corrupto") → no entregues el arreglo directamente, indica "detener el entrenamiento, preservar el estado, notificar al responsable". La acción correcta para una causa raíz de alto riesgo es detener, no parchear.

Cada fix_on_mismatch incluye un rollback — para que la persona pueda revertir si la aplicación falla.

Escribir trace en cada paso (obligatorio)

Después de cada paso, añade una entrada al array trace en diagnosis_state-<session_id>.yaml (un archivo independiente por diagnóstico concurrente, diferenciado por session_id):

- {step: N, action: triage|load_index|quickly_check|load_full|run_check|hit|miss|tier3|feedback, ...}

El trace es la única base para la atribución de errores de diagnóstico (consulta el final de references/diagnosis-procedure.md en "Atribución de errores de diagnóstico"): cuando haya un error, primero lee el trace para determinar si es un error del caso (modificar la base de conocimiento) o un error de ejecución (modificar la habilidad). No escribir el trace = imposible atribuir = se podría modificar un caso correcto por error.

Lo que NO debes hacer

• No decidas la causa raíz por el ingeniero; presenta una lista estructurada para que la persona ejecute y pegue los resultados.
• No intentes un tercer caso de forma consecutiva; si dos no resuelven, deriva a un humano (protección en serie contra errores de diagnóstico, consulta references/diagnosis-procedure.md).
• No cargues el profiler completo en el contexto; recórtalo al rank relevante + final de la pila.
• No uses el enfoque de grep de interrupt para crear un quickly_check de precision (las categorías tienen formas diferentes).
• Si te interrumpen → /skill:resume-diagnosis.