pillumina/ascend-sleuth

진단

Ascend 문제의 핵심 진단 루프. 당신은 보조 위치 도구입니다. 수정 사항은 당신의 제안이며, 사람이 수동으로 고객 환경에 적용합니다. 당신은 자동으로 프로덕션 환경을 변경하지 않습니다.

사용 시기

훈련 또는 추론 중 문제가 발생했을 때(중단/정밀도/성능), 그리고 bash를 실행할 수 있는 에이전트 안에 있을 때 사용합니다. 인터럽트 후 재개하려면 → /skill:resume-diagnosis.

긴급 상황 (프로덕션 중단)

고객이 "긴급 / 프로덕션 중단 / 먼저 복구"라고 말할 때, 진단 목표가 "원인 찾기"에서 "먼저 안정화"로 변경됩니다.

1. 먼저 지식 베이스를 확인합니다——일치하는 사례(예: 알려진 안전 롤백)가 있으면 바로 제공합니다. 이것이 가장 빠릅니다. 지식 베이스의 구체적인 해결책이 항상 일반적인 응급 처치 요령보다 우선합니다.
2. 빠르게 일치하는 항목이 없을 때는 고객이 이미 제공한 정보를 바탕으로 단계별로 안정화 제안을 합니다.
   • 최근 24-48시간 동안 변경한 사항을 고객에게 묻습니다(스크립트/설정, 프레임워크 버전, 드라이버/펌웨어/CANN, 데이터, 모델 코드) —— 사고는 대부분 최근 변경에서 비롯됩니다.
   • 기본 상태 확인: npu-smi info (카드가 살아있는지), hccl top (통신 토폴로지가 정상인지)
   • 로그 스택의 끝부분을 보고 어느 계층에서 문제가 발생했는지 파악합니다.
   • 복구 가능한지 확인: 이전 체크포인트로 롤백 후 재시작 / 사양 낮추기(EP 끄기, 배치 크기 줄이기) / 데몬 재시작
3. 깊이 있는 조사나 사후 분석(postmortem)을 작성하지 마십시오——나중에 /skill:to-postmortem으로 보충합니다.

절차 (핵심 루프는 references/diagnosis-procedure.md 참조)

실행 모델: 당신은 어떤 환경에도 접근하지 않습니다. 모든 정보(로그, 버전, 오류 메시지, 환경 변수)는 엔지니어가 고객으로부터 제공받아 붙여넣습니다. 당신의 적극적인 역할은 정보가 부족할 때, 엔지니어가 고객에게 무엇을 요청해야 하는지 명확히 알려주는 것입니다. 사례 내의 command는 "확인해야 할 검사"입니다: 제공된 정보를 바탕으로 판단하거나, 고객에게 실행 후 출력을 다시 붙여넣도록 요청하는 것입니다. 당신이 직접 pip/env/grep을 실행하는 것이 아닙니다.

이어하기: 완료되지 않은 diagnosis_state-*.yaml 파일(각 동시 진단마다 하나의 파일)이 존재하는 경우, 먼저 "완료되지 않은 진단이 있습니다. /skill:resume-diagnosis로 이어할까요?"라고 묻습니다. 엔지니어가 직접 이어하기를 기억하도록 하지 마십시오.

1. 증상 수집 + 프레임워크 확인 (모두 엔지니어가 제공한 정보로부터)

   • 오류 메시지, HCCL_*/ASCEND_*/NPU_* 환경 변수 값, 버전 조합(엔진 버전 + CANN + HDK/드라이버 + 아키텍처 A2/A3/A5) —— 모두 고객에게서 받습니다.
   • 정보가 불완전하면 적극적으로 질문합니다: 명확하지 않으면 적극적으로 묻습니다——①증상(무슨 오류/언제 중단) ②고객의 버전 조합(엔진/CANN/HDK/아키텍처) ③로그/profiler 위치(관련 rank + 스택 끝 부분을 붙여넣기). 기다리지 마십시오.
   • 프레임워크는 제공된 정보/오류로 판단합니다 (로그 내 mindspeed/vllm 등의 문자열); 판단이 안 되면 엔지니어에게 직접 "고객이 어떤 프레임워크를 사용합니까?"라고 묻습니다. pip list를 실행하지 마십시오 (그것은 당신의 로컬 환경이며 고객과 무관합니다).
   • 적극적으로 로그를 자릅니다: 엔지니어에게 실패한 rank + 오류 스택 끝 부분만 붙여넣도록 요청하고, 절대 전체 profiler를 붙여넣지 않도록 합니다. 진단 세션의 컨텍스트의 80%는 로그입니다. 전체를 붙여넣으면 스마트 존(~120K 토큰이 추론에 가장 예리함)을 벗어나 추론 품질이 급격히 떨어집니다.

2. 분류 → triage-tree.yaml (Tier 1)

   • 증상이 일치하는 분기 → 네임스페이스로 라우팅 (training|inference/<framework>/ 우선, 그다음 common/)
   • 트라이지(triage) 결정은 trace에 기록합니다 (어느 분기, 어떤 네임스페이스로 라우팅되었는지, 카테고리)
   • 트라이지 다중 분기 약한 일치/신뢰도 낮음 → 우아한 성능 저하(graceful degradation): 모든 네임스페이스 인덱스를 로드하여 quickly_check로 필터링합니다(인덱스는 저렴하므로 성능 저하 비용이 통제 가능합니다).
   • 프레임워크를 감지하지 못함 → common/만 검색; 분류 불가 → 직접 Tier 3으로 이동합니다.

3. 2단계 Tier 2 로드

   • 1단계: knowledge/_index.yaml (scripts/build_index.py가 생성한 일회성 인덱스, 모든 id/title/symptoms/quickly_check/category/confidence + file 위치 포함)을 읽고, 일치하는 네임스페이스의 항목을 가져와 quickly_check(primary→fallback)를 사용하여 제공된 정보를 바탕으로 후보를 ≤5개로 필터링합니다. 검사 항목에 정보가 부족하면 고객에게 추가로 요청해야 할 사항을 기록합니다. 인덱스가 없거나 --check가 만료되었다고 보고하면 → 폴백(fallback): 위 인덱스 필드만을 위해 파일을 하나씩 읽고 scripts/build_index.py를 다시 실행하라는 알림을 줍니다.
   • 빈 라이브러리 알림 (콜드 스타트): 일치하는 네임스페이스가 비어 있는 경우(아직 사례가 없음), 조용히 성능 저하시키지 말고 사용자에게 알립니다: "현재 knowledge/<ns>/에는 검증된 사례가 없습니다. 다음을 할 수 있습니다: ①깊이 있는 조사 계속(5단계) ②진단 후 /skill:to-postmortem을 실행하여 첫 번째 사례로 축적 ③수동 전환". 빈 라이브러리를 "이 도구는 아무것도 할 줄 모른다"고 느끼게 하지 마십시오.
   • primary가 일치하지 않지만 fallback이 일치하는 경우 → 여전히 검증 단계로 이동하되, low_confidence 표시를 합니다.
   • 카테고리가 quickly_check의 형태를 결정합니다: interrupt는 오류 시그니처를 grep으로 검색, precision은 수치 임계값(loss>1e3, has_nan), performance는 profiler 지표(comm_ratio>0.4)를 사용합니다. 혼용하지 마십시오.
   • 2단계: 후보를 전체 로드하고, confidence.score 내림차순으로 검증에 들어갑니다. 여러 후보가 있으면 명시합니다: "N개의 후보가 일치했습니다. 가장 가능성이 높은 <id>(confidence <score>)를 먼저 검증합니다." 엔지니어가 상황을 알 수 있도록 합니다; 엔지니어는 "이것은 건너뛰고 다음 것을 시도"라고 말할 수 있습니다.

4. 진단 확인 검증

   • 후보 사례의 diagnosis 확인 항목을 순서대로 검증합니다 (제공된 정보를 바탕으로 단계를 건너뛰지 않음); 특정 단계에 정보가 부족하면 → 엔지니어에게 고객에게 요청하도록 알립니다(또는 고객이 해당 명령을 실행하고 출력을 붙여넣도록 함); 불일치하고 fix_on_mismatch가 있는 경우 → 수정 사항을 제시합니다 (먼저 심각도 확인, 아래 참조).
   • 버전 소프트 매칭(soft matching): 후보 사례의 compat (framework/cann/hdk, 채워진 차원)을 고객의 버전 조합과 차원별로 비교합니다——하나라도 일치하지 않으면 → version_mismatch 표시, confidence를 임시로 낮춥니다. 사례는 여전히 후보로 남깁니다(하드 제외하지 않음); 채워지지 않은 차원은 건너뜁니다.
   • 일치 → 근본 원인 + 수정 사항을 출력하고 6단계로 이동합니다.
   • 모든 후보가 일치하지 않음 → 깊이 있는 조사(5단계).

5. 깊이 있는 조사 (Tier 2 불일치)

   • 스크립트 도구가 통합된 경우 (references/script-integration.md 참조), 카테고리에 따라 사용: interrupt→로그/코어 덤프, precision→mem-analyze, performance→ascend-profile-analyze/bench-run. 현재 스켈레톤 단계에서는 이러한 스크립트가 대부분 아직 통합되지 않았을 수 있습니다——호출할 수 있는 척 하지 말고 엔지니어에게 정직하게 알려주십시오.
   • Tier 3 키워드 검색 postmortems/ (rg -l '<keyword>' postmortems/, top-3 읽기; postmortems/inbox/의 미검토 초안 포함——사용 가능하지만 사람이 검토하지 않았음을 표시). trace는 {action: tier3, keyword, files_read}를 기록합니다——Tier 3 구제율 지표(docs/metrics.md)는 이 통계를 기반으로 합니다. 이것이 스켈레톤 단계에서 실제로 사용할 수 있는 폴백(fallback)입니다.
   • 모두 없음 → 정직하게 "지식 베이스가 이 문제를 다루지 않습니다. 수동 조사가 필요합니다. 원인을 찾은 후 /skill:to-postmortem을 사용하여 축적하면 다음 번에 일치할 수 있습니다."라고 말합니다. 사람 + 에이전트의 공동 분석입니다.

6. 산출물

   • resolution: resolved | escalated | unknown
   • Tier-2 일치: 일반적인 포스트모템(postmortem) 초안
   • Tier-2 불일치하지만 최종 해결됨: 당신이 초안을 작성한 후보 사례를 포함하는 포스트모템 (quickly_check + diagnosis + 낮은 confidence), /skill:knowledge-groom으로 전달하여 검증
   • 전체 trace는 diagnosis_state-<session_id>.yaml에 저장됩니다(각 동시 진단마다 하나의 파일; 템플릿은 diagnosis_state.yaml.example 참조)
   • 결과 피드백 루프 (학습 루프 종료, 중요): 수정 사항을 제시한 후, 엔지니어가 적용하고 결과를 보고할 때까지 기다리십시오——"적용 후 해결되었습니까? (해결됨 / 해결 안 됨 / 부분 해결)". 결과를 해당 사례의 confidence에 다시 씁니다: 해결됨 → hits += 1; 해결 안 됨 → misdiagnoses += 1, last_hit 업데이트. 이 단계를 묻지 않으면 confidence/오진율은 초기값 그대로이며, 전체 학습 메커니즘은 공회전합니다.
   • 피드백 캡처 구조화 (기억에 의존하지 않음): 수정 사항을 제시하고 세션을 마무리하기 전에 상태 파일에 feedback_pending: <case-id>를 기록합니다. /skill:diagnose 또는 /skill:resume-diagnosis가 시작될 때마다 먼저 활성 상태 파일을 스캔합니다——해당 표시를 발견하면 먼저 "이전 <case-id>의 수정 사항을 적용한 후 해결되었습니까?"라고 묻고, 답변에 따라 confidence를 다시 쓰고(위 규칙), trace에 {action: feedback, case, outcome: resolved|not_resolved|partial}을 기록하고, 표시를 지웁니다. 피드백 캡처는 전체 학습 루프의 처리량 상한입니다——표시가 파일에 기록되므로 누구의 기억에도 의존하지 않습니다.
   • 축적은 이 단계에 이미 포함됨: 일치 = 일반 포스트모템, 불일치 = 후보 사례가 포함된 포스트모템. 이 단계에서 이미 생성되었습니다. 이번 진단이 /diagnose를 통해 위치 파악된 것이 아닌 경우에만(예: Kimi/수동으로 확인했거나, 세션 종료 훅이 설정되지 않아 포스트모템이 생성되지 않은 경우), /skill:to-postmortem을 통한 수동 축적이 필요합니다.

일치 시 출력 형식

하나의 사례가 일치하면 엔지니어에게 구조화되고 추적 가능한 출력을 제공합니다(단순히 수정 사항만 던지지 않음):

<CASE-ID> 일치 (confidence <score>, 과거 일치 <hits>회 / 오진 <misdiagnoses>회)
버전 일치: <완전 일치 | version_mismatch: 이 사례는 <versions>에서 검증됨, 고객은 <customer versions>임——주의해서 사용>
일치 증상: <이번 라운드에서 일치한 symptoms>
근본 원인(root cause): <root_cause>
수정(fix): <fix> (fix_type: <env-var|config-change|code-patch|pending-investigation>, severity: <benign|service-affecting|data-loss-risk>, <fix_side_effects>)
  → fix_type이 표시 방식을 결정: env-var/config-change는 실행 가능한 명령을 직접 제공; code-patch는 변경 파일 + diff 요점 제공(직접 실행 불가); pending-investigation은 조사 제안 제공
롤백(rollback): <rollback>
적용 후 확인: <수정 사항이 적용되었는지 확인하는 방법>

confidence 보정 (엔지니어가 얼마나 신뢰해야 하는지 판단할 수 있도록): >0.8 높은 신뢰도, 직접 적용; 0.5–0.8 중간 신뢰도, 적용과 동시에 계획 B 준비; <0.5 단서로만 사용, 수동 조사에 중점. 기준을 명확히 설명하고 엔지니어가 0.86이 높은지 중간인지 추측하지 않도록 합니다.

심각도 게이트 (일치 후 먼저 확인)

후보 사례의 severity 필드를 읽고 출력 전략을 결정합니다:

• benign → 수정 사항을 직접 제공
• service-affecting → 수정 사항을 제공하지만, fix_side_effects (예: requires-restart)를 표시하여 사람이 조정 창을 조정할 수 있도록 함
• data-loss-risk (예: "체크포인트가 오염될 수 있음") → 수정 사항을 직접 제공하지 않고 "훈련을 중단하고 현장을 보존하며 소유자에게 알림"을 출력합니다. 고위험 근본 원인에 대한 올바른 조치는 패치가 아니라 중단입니다.

각 fix_on_mismatch에는 rollback이 포함됩니다——사람이 적용에 실패할 경우 되돌릴 수 있습니다.

매 단계마다 trace 작성 (필수 요구 사항)

각 단계 후에 diagnosis_state-<session_id>.yaml (각 동시 진단마다 session_id로 구분된 독립 파일)의 trace 배열에 하나를 추가합니다:

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

trace는 오진 원인을 추적하는 유일한 근거입니다(references/diagnosis-procedure.md 마지막 부분의 "오진 원인 분석" 참조): 오진 발생 시 trace를 먼저 읽어 사례 오류(라이브러리 수정)인지 실행 오류(스킬 수정)인지 판단합니다. trace를 작성하지 않으면 = 원인을 추적할 수 없음 = 올바른 사례를 잘못 수정할 수 있습니다.

하지 말아야 할 것

• 남을 대신하여 근본 원인을 결정하지 마십시오——구조화된 체크리스트를 제공하면 사람이 실행한 후 결과를 붙여넣습니다.
• 세 번째 사례를 연속으로 시도하지 마십시오——두 번 해결되지 않으면 수동 전환합니다(오진 보호의 직렬 보호, references/diagnosis-procedure.md 참조).
• 전체 profiler를 컨텍스트에 붙여넣지 마십시오——관련 rank + 스택 끝 부분으로 자릅니다.
• interrupt의 grep 방식을 사용하여 precision의 quickly_check를 구축하지 마십시오(카테고리 형태가 다름).
• 인터럽트 발생 시 → /skill:resume-diagnosis