| name | example-helper |
| description | XM10 예제 트러블슈팅 — 사용자가 "Ex.XX 안 돼" / "빌드 실패" / "LED 안 켜져" 등 호소 시,
해당 예제 .c 의 @warning + README ⚠️ 섹션 + docs/troubleshooting.md 를 인용해 답한다.
TRIGGER when:
- 사용자가 "Ex.XX" + 부정형 ("안 돼", "안 켜져", "실패", "에러") 동시 언급
- 사용자가 "예제 빌드 실패", "플래시 안 됨", "CDC 연결 실패", "LED 안 켜져" 등 트러블 키워드
- 사용자가 "/example-helper" 명시 호출
- 사용자가 Phase 6 (handoff) 통과 후 첫 코드 변경 시도 중 막힘
DO NOT TRIGGER when:
- 환경 구축 단계 (Phase 0~5 진행 중 → student-onboard 가 처리)
- 사용자가 새 예제 작성/기여 요청 (편집 작업)
- 일반 API 질문 (→ docs/api-reference/ 직접 참조)
|
example-helper Skill
사용자가 특정 예제에서 막혔을 때 빠르게 진단·답변하는 dispatcher.
Process
1. 증상 추출
사용자 메시지에서 다음 4개 정보를 파악:
- 예제 번호 (Ex.XX) — 없으면 "어느 예제인가요?" 질문
- 단계 — 빌드 / 플래시 / 실행 / 결과 확인
- 에러 메시지 전문 (있다면 그대로 받기, 변형 X)
- HW 상태 — 보드 전원, ST-Link, USB-CDC 케이블 연결 여부
2. 1차 참조 — 해당 예제 자체
해당 예제 폴더 (examples/<번호>_*/) 에서:
*.c 헤더의 @note / @warning / @see 블록README.md 의 "⚠️ 흔한 실수" 섹션README.md 의 "2️⃣ 사전 지식" — 사용자가 빠뜨린 선행 학습이 있는지
대부분의 사용자 질문은 이 단계에서 해결됨.
3. 2차 참조 — 일반 트러블슈팅
docs/troubleshooting.md 의 카테고리:
- 빌드 에러 (
undefined reference, region overflowed, file not found)
- 플래시 에러 (
No ST-Link detected, Target no device found)
- 한글 경로 / MAX_PATH
- USB-CDC 충돌 (PhAI Studio 동시점유)
- MSC mount 실패
4. 3차 참조 — API 레퍼런스
docs/api-reference/ 의 함수 시그니처 + 예시 + ⚠️ 섹션.
사용자가 API 호출 방식이 틀린 경우 인용.
5. 응답 포맷 (사용자 친화)
[증상] <사용자 보고 요약>
[원인 후보] <1~3개 가장 가능성 높은 것>
[해결]
1. <첫 시도 — 가장 비용 낮음>
2. <두 번째 시도>
[참조] <예제 README 또는 docs 경로>
[그래도 안 되면] <GitHub Issue 템플릿 안내>
자주 묻는 패턴 (Cheatsheet)
| 증상 | 1차 의심 | 빠른 해결 |
|---|
| Ex.07/08/09 — "PhAI Studio 안 잡힘" | USB-CDC 동시점유 | 시리얼 터미널 종료, PhAI 단독 실행 (@warning 참조) |
| Ex.10* — "MSC 마운트 실패" | FAT32 + 32KB cluster 미준수 | USB 메모리 포맷 재시도 (FAT32, AU=32KB) |
| Ex.14~17 — "제어 발산" | PD gain 너무 큼 | gain 절반으로 줄이고 재실험 |
undefined reference to '__weak_xxx' | XM_Lib --whole-archive 미적용 | SDK 폴더 손상 의심, Phase 2 재실행 |
| "LED 안 켜짐" | 플래시 실패 또는 hang | Phase 4/5 재진행 |
Anti-pattern (이 Skill 이 하지 말 것)
- 코드를 임의로 수정하지 않음. 사용자가 직접 시도하도록 안내만.
- 정확한 에러 메시지 없이 추측 진단 금지. "에러 메시지 전체를 그대로 붙여주세요" 먼저 요청.
- 환경 구축 (Phase 0~5) 영역은 본 Skill 이 다루지 않음 —
student-onboard 호출 권유.
막혔을 때
- 본 Skill 로도 해결 안 되면: GitHub Issue (
bug_report.yml) 템플릿 안내 + 사용자가 시도한 단계 / 에러 메시지 / HW 상태 첨부 권유.
