pillumina/ascend-sleuth

Diagnose

O loop central de diagnóstico para problemas Ascend. Você é uma ferramenta auxiliar de localização — a correção é sua sugestão, aplicada manualmente por uma pessoa no ambiente do cliente; você não altera produção automaticamente.

Quando usar

Quando ocorre um problema de treinamento ou inferência (interrupção / precisão / desempenho) e você está em um agente que pode executar bash. Se for interrompido, continue com → /skill:resume-diagnosis.

Situações de emergência (interrupção de produção)

Quando o cliente diz "emergência / produção parou / precisamos restaurar primeiro", o objetivo do diagnóstico muda de "encontrar causa raiz" para "estabilizar primeiro":

1. Ainda consulte a base de conhecimento primeiro — se houver um caso correspondente (ex.: rollback de segurança conhecido), forneça-o diretamente; é o mais rápido. O antídoto específico na base de conhecimento sempre supera uma cartilha genérica de primeiros socorros.
2. Se não houver correspondência rápida, com base nas informações já fornecidas pelo cliente, dê sugestões de estabilização passo a passo:
   • Pergunte o que o cliente mudou nas últimas 24-48h (scripts/configuração, versão do framework, driver/firmware/CANN, dados, código do modelo) — a maioria dos incidentes vem de mudanças recentes
   • Verificações básicas de saúde: npu-smi info (a placa está viva?), hccl top (topologia de comunicação normal?)
   • Veja o final da pilha de logs para localizar onde ocorreu a falha
   • É possível restaurar? Rollback para o último checkpoint / Reduzir recursos (desligar EP, reduzir batch) / Reiniciar daemon
3. Não faça investigação aprofundada, não escreva postmortem — depois, use /skill:to-postmortem para complementar.

Fluxo (veja references/diagnosis-procedure.md para o loop central detalhado)

Modelo de execução: Você não acessa nenhum ambiente. Todas as informações — logs, versões, erros, variáveis de ambiente — são fornecidas pelo engenheiro a partir do cliente (copiadas e coladas). Seu papel ativo é quando a informação é insuficiente, indicar claramente ao engenheiro o que solicitar ao cliente. Os command em um caso são "verificações a confirmar": julgue com base nas informações já fornecidas ou peça ao cliente para executar e colar a saída de volta — você não executa pip/env/grep diretamente.

Continuação: Se existir um diagnosis_state-*.yaml não concluído (um arquivo por diagnóstico concorrente), primeiro pergunte "Há um diagnóstico não concluído. Deseja continuar com /skill:resume-diagnosis?" — não deixe o engenheiro lembrar de executar resume.

1. Coletar sintomas + confirmar framework (tudo a partir das informações fornecidas pelo engenheiro)

   • Mensagem de erro, valores de variáveis de ambiente HCCL_*/ASCEND_*/NPU_*, combinação de versões (versão do motor + CANN + HDK/driver + arquitetura A2/A3/A5) — tudo solicitado ao cliente
   • Se a informação estiver incompleta, pergunte ativamente: se não estiver claro, pergunte — ① sintomas (qual erro / quando travou) ② combinação de versões do cliente (motor/CANN/HDK/arquitetura) ③ onde estão os logs/profiler (cole o rank relevante + final da pilha). Não espere passivamente
   • Identifique o framework a partir das informações/erros fornecidos (menções a mindspeed/vllm nos logs, etc.); se não conseguir identificar, pergunte diretamente ao engenheiro "Qual framework o cliente está usando?", não execute pip list (esse é seu ambiente local, não tem relação com o cliente)
   • Corte os logs ativamente: peça ao engenheiro para colar apenas o rank com falha + o final da pilha de erro, nunca cole o profiler completo — o contexto de uma sessão de diagnóstico é 80% logs; colocar tudo empurra para fora da smart zone (~120K tokens, onde o raciocínio é mais preciso) e a qualidade do diagnóstico despenca

2. Classificar → Carregar triage-tree.yaml (Tier 1)

   • Corresponder sintomas a um ramo → Roteirizar para um namespace (primeiro training|inference/<framework>/, depois common/)
   • Registrar a decisão de triagem no trace (qual ramo foi correspondido, para quais namespaces foi roteado, categoria)
   • Se a triagem tiver correspondência fraca em múltiplos ramos / baixa confiança → Degradação graciosa: carregar o índice de todos os namespaces e usar quickly_check para filtrar (índice é barato; custo de degradação controlável)
   • Se o framework não for detectado → pesquisar apenas em common/; se não for possível classificar → ir diretamente para Tier 3

3. Carregamento em duas fases (Tier 2)

   • Fase um: Ler knowledge/_index.yaml (índice único gerado por scripts/build_index.py, contendo todos os id/title/symptoms/quickly_check/category/confidence + localização file), pegar entradas do namespace correspondido, usar quickly_check (primário → fallback) comparando com as informações já fornecidas para filtrar candidatos ≤5; se faltar informação para uma verificação, anote o que precisa ser solicitado ao cliente. Se o índice estiver faltando ou --check reportar expiração → fallback: ler apenas os campos de índice arquivo por arquivo e lembrar de executar scripts/build_index.py para reconstruir
   • Aviso de base vazia (cold start): Se o namespace correspondido estiver vazio (ainda sem casos), não degrade silenciosamente — informe ao usuário "O diretório knowledge/<ns>/ ainda não tem casos verificados. Você pode: ① continuar com investigação aprofundada (passo 5) ② após o diagnóstico, executar /skill:to-postmortem para consolidar como o primeiro caso ③ escalar para um humano". Não deixe a impressão de que "essa ferramenta não sabe de nada".
   • Se o primary não corresponder mas o fallback corresponder → ainda entre em verificação, marque como low_confidence
   • A categoria determina a forma do quickly_check: interrupt usa grep na assinatura do erro, precision usa limites numéricos (loss>1e3, has_nan), performance usa métricas do profiler (comm_ratio>0.4) — não misture
   • Fase dois: Carregar completamente os candidatos, ordenar por confidence.score decrescente e entrar em verificação. Quando houver múltiplos candidatos, indique claramente: "Encontrados N candidatos. Vou verificar primeiro o mais provável <id> (confiança <score>)", para que o engenheiro saiba; o engenheiro pode dizer "Pule este, tente o próximo"

4. Verificar as checagens de diagnóstico

   • Verificar sequencialmente os itens de diagnosis do caso candidato (comparando com as informações já fornecidas, sem pular etapas); se faltar informação em algum passo → peça ao engenheiro para solicitar ao cliente (ou peça para o cliente executar o comando e colar a saída); se houver mismatch e existir fix_on_mismatch → forneça a correção (primeiro veja a severidade, abaixo)
   • Correspondência flexível de versões: compare cada dimensão preenchida do compat do caso candidato (framework/cann/hdk) com a combinação de versões do cliente — se qualquer dimensão não corresponder → marque como version_mismatch, reduza temporariamente a confiança, o caso ainda é candidato (não exclua rigidamente); dimensões não preenchidas são ignoradas
   • Se corresponder → produza causa raiz + correção, vá para o passo 6
   • Se todos os candidatos falharem → investigação aprofundada (passo 5)

5. Investigação aprofundada (Tier 2 não correspondeu)

   • Se a ferramenta Script estiver integrada (veja references/script-integration.md), use por categoria: interrupt→logs/core dump, precision→mem-analyze, performance→ascend-profile-analyze/bench-run. Nesta fase de esqueleto, a maioria desses Scripts provavelmente não está integrada — não finja que pode chamá-los; seja honesto com o engenheiro.
   • Pesquisa por palavras-chave no Tier 3 postmortems/ (rg -l '<keyword>' postmortems/, top-3 leia trechos; inclui postmortems/inbox/ com rascunhos não revisados — utilizáveis, mas marque como não revisados por humano). Registre no trace {action: tier3, keyword, files_read} — a métrica de taxa de recuperação do Tier 3 (docs/metrics.md) depende deste registro. Este é o verdadeiro fallback utilizável nesta fase de esqueleto
   • Se nada for encontrado → seja honesto: "A base de conhecimento não cobre este problema. É necessária investigação manual. Após a localização, use /skill:to-postmortem para consolidar; na próxima vez, será correspondido." Análise conjunta humano + agente

6. Saída

   • resolution: resolved | escalated | unknown
   • Tier-2 correspondeu: Rascunho de postmortem padrão
   • Tier-2 não correspondeu mas resolvido no final: Postmortem contendo um caso candidato rascunhado por você (quickly_check + diagnosis + confidence baixa), submeta para /skill:knowledge-groom verificar
   • Trace completo salvo com diagnosis_state-<session_id>.yaml (um arquivo por diagnóstico concorrente; modelo em diagnosis_state.yaml.example)
   • Fechamento do ciclo de feedback (loop de aprendizado crítico): Após fornecer a correção, espere o engenheiro aplicar e relatar o resultado — pergunte "Após aplicar, resolveu? (Resolvido / Não resolvido / Parcialmente resolvido)". O resultado atualiza a confiança do caso: Resolvido → hits += 1; Não resolvido → misdiagnoses += 1, atualize last_hit. Se não perguntar, confiança/taxa de erro permanecem nos valores iniciais; todo o mecanismo de aprendizado fica ocioso.
   • Captura estruturada de feedback (sem depender de memória): Após fornecer a correção, antes de encerrar a sessão, escreva no arquivo de estado feedback_pending: <case-id>. Toda vez que /skill:diagnose ou /skill:resume-diagnosis iniciar, primeiro verifique os arquivos de estado ativos — se encontrar a marcação, pergunte primeiro "A correção do caso <case-id> de antes resolveu depois de aplicada?", atualize a confiança conforme a resposta (regra acima), registre no trace {action: feedback, case, outcome: resolved|not_resolved|partial}, e limpe a marcação. A captura de feedback é o gargalo de vazão de todo o loop de aprendizado — com a marcação no arquivo, não depende da memória de ninguém
   • Consolidação já está neste passo: Correspondência = postmortem padrão; Não correspondência = postmortem com caso candidato; este passo já gera. Somente se o diagnóstico não foi feito via /diagnose (ex.: verificado manualmente ou com Kimi, ou se não havia hook de fim de sessão e o postmortem não foi gerado), aí sim use /skill:to-postmortem para consolidar manualmente.

Formato de saída quando corresponde

Quando um caso corresponde, forneça ao engenheiro uma saída estruturada e rastreável (não apenas uma linha de correção):

Correspondeu a <CASE-ID> (confiança <score>, histórico: <hits> acertos / <misdiagnoses> erros)
Correspondência de versão: <completa | version_mismatch: este caso foi verificado em <versões>, cliente é <versões do cliente> — use com cautela>
Sintomas correspondidos: <sintomas correspondidos nesta rodada>
Causa raiz: <root_cause>
Correção: <fix> (tipo: <env-var|config-change|code-patch|pending-investigation>, severidade: <benign|service-affecting|data-loss-risk>, <efeitos colaterais>)
  → O tipo de correção define a apresentação: env-var/config-change forneça comando executável diretamente; code-patch forneça arquivo modificado + pontos principais do diff (não executável diretamente); pending-investigation forneça sugestões de investigação
Rollback: <rollback>
Verificação pós-aplicação: <como verificar se a correção funcionou>

Calibração da confiança (para o engenheiro julgar o quanto confiar): >0.8 alta confiabilidade, aplicar diretamente; 0.5–0.8 confiabilidade média, aplicar mas preparar plano B; <0.5 apenas como dica, focar em investigação manual. Explique a régua para que o engenheiro não precise adivinhar se 0.86 é alto ou médio.

Portão de severidade (verifique primeiro após correspondência)

Leia o campo severity do caso candidato para decidir a estratégia de saída:

• benign → Forneça a correção diretamente
• service-affecting → Forneça a correção, mas marque fix_side_effects (ex.: requires-restart), para que a pessoa coordene a janela
• data-loss-risk (ex.: "checkpoint pode estar corrompido") → Não forneça a correção diretamente, produza "Pare o treinamento, preserve a cena, notifique o proprietário". Para causas raiz de alto risco, a ação correta é parar, não aplicar patch

Cada fix_on_mismatch vem com rollback — a pessoa pode reverter se a aplicação falhar.

Escreva trace a cada passo (obrigatório)

Após cada passo, adicione ao array trace no arquivo diagnosis_state-<session_id>.yaml (um arquivo independente por diagnóstico concorrente, diferenciado por session_id) uma entrada:

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

O trace é a única base para atribuição de erro de diagnóstico (veja o final de references/diagnosis-procedure.md, seção "Atribuição de erro de diagnóstico"): quando um diagnóstico erra, leia o trace primeiro para determinar se foi erro de caso (altere a base) ou erro de execução (altere o skill). Não escrever trace = impossível atribuir = pode corromper casos corretos.

O que não fazer

• Não determine a causa raiz pela pessoa — forneça uma lista estruturada; a pessoa executa e cola o resultado de volta
• Não tente um terceiro caso consecutivamente — duas falhas = escale para humano (proteção serial contra erro de diagnóstico, veja references/diagnosis-procedure.md)
• Não coloque o profiler completo no contexto — corte para o rank relevante + final da pilha
• Não use a abordagem de grep de interrupt para construir o quickly_check de precision (as categorias têm formas diferentes)
• Se for interrompido → /skill:resume-diagnosis