# task-1112.1 완료 보고서: 스킬 사용 추적 시스템 & 대시보드 연동

## SCQA

**S**: 아누 시스템에 87개(실제 SKILL.md 보유 86개) 스킬이 등록되어 운영 중이며, 대시보드(http://100.76.130.39:8000/dashboard/)에서 조직/프로젝트/시스템/토큰 등 9개 뷰를 제공하고 있다.

**C**: 스킬 사용 추적 시스템이 전무하여 어떤 스킬이 얼마나 사용되는지 파악 불가. 3/26 수동 JSONL 분석 결과 Skill 도구 호출은 3개 스킬/12회에 불과하나, 이는 수동 분석의 한계이지 실제 사용량은 아닐 수 있음.

**Q**: 스킬 사용 현황을 실시간으로 파악하고, 대시보드에서 스킬 목록/사용 통계/활성 스킬을 확인할 수 있는 시스템을 구축할 수 있는가?

**A**: 스킬 레지스트리 자동 생성 + JSONL 기반 사용 로깅 + 대시보드 API 4개 + SkillView 프론트엔드를 구현 완료. pytest 6건 전체 통과, pyright 에러 0건, black/isort 준수. 86개 스킬 정상 로드, deprecated 1건(conversion-copywriter) 자동 감지.

---

## 구현 내용

### 백엔드 (server.py DataLoader 확장)
- `load_skill_registry()`: /home/jay/workspace/skills/ 스캔, YAML frontmatter 파싱, 86개 스킬 메타데이터 로드
- `get_skill_usage_stats(period)`: skill-usage.jsonl 기간별 집계 (1d/7d/30d/90d)
- `get_active_skills()`: task-timers.json에서 running 태스크 추출
- `log_skill_usage(data)`: JSONL append 로깅

### API 엔드포인트 (4개 신규)
- GET /api/skills → 전체 스킬 목록 (86개, 카테고리/상태 포함)
- GET /api/skill-usage?period=7d → 기간별 사용 통계
- GET /api/skill-usage/active → 현재 활성 태스크 목록
- POST /api/skill-log → 사용 이벤트 기록

### 프론트엔드 (SkillView.js 신규)
- 요약 카드 4개 (총 스킬/활성/호출 수/deprecated)
- 스킬 목록 (검색/카테고리/상태 필터링)
- 사용 통계 (Top 10 바차트, 팀별 분포, 일별 추이)
- 활성 스킬 실시간 표시 (30초 폴링)

---

## 생성/수정 파일

### 신규 생성
- `dashboard/components/SkillView.js` (604줄, 32,706 bytes)
- `dashboard/data/skill-usage.jsonl` (빈 파일, 로깅 대기)
- `teams/dev1/tests/test_skill_tracker.py` (236줄, 8,092 bytes)
- `memory/meetings/task-1112.1-meeting.md` (미팅 기록)
- `memory/tasks/task-1112.1-plan.md` (계획서)
- `memory/tasks/task-1112.1-context.md` (맥락노트)
- `memory/tasks/task-1112.1-checklist.md` (체크리스트)

### 수정
- `dashboard/server.py` (DataLoader에 4개 메서드 + DashboardHandler에 4개 엔드포인트 추가)
- `dashboard/components/App.js` (스킬 탭 추가 + 조건부 렌더링)
- `dashboard/index.html` (SkillView.js 스크립트 로드)

---

## 테스트 결과

- pytest: **6 passed, 0 failed** (0.13s)
  - test_load_skill_registry_basic
  - test_load_skill_registry_deprecated
  - test_get_skill_usage_stats_empty
  - test_get_skill_usage_stats_with_data
  - test_log_skill_usage
  - test_get_active_skills
- pyright: **0 errors, 0 warnings, 0 informations**
- black + isort: **준수**
- 기존 dashboard 테스트: **6 passed** (dashboard/tests/test_server.py, 회귀 없음)

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **datetime.utcnow() deprecation** — `datetime.now(tz=None)`으로 교체 (server.py 2곳, test 3곳)
2. **YAML 파싱 실패 가능성** — deprecated 스킬의 description에 콜론 포함 시 파싱 오류 → _fallback_parse_fm 폴백 파서 구현
3. **skills/shared 디렉토리에 SKILL.md 없음** — 87개 디렉토리 중 1개(shared)는 SKILL.md 미보유, 자동 스킵 처리 정상

4. **프론트엔드-백엔드 필드명 불일치** — SkillView.js가 `call_count`/`skill_name` 접근, 서버는 `count`/`skill_id` 반환 → `count`/`skill_id`로 통일. 활성 스킬 카드 `name` → `task_id`+`description`으로 수정
   - 마아트 독립 검증에서 발견, 즉시 수정 완료

### 범위 외 미해결 (4건)
1. **Skill 도구 호출 자동 캡처 불가** — Claude Code 내부 동작으로 외부 훅 불가. 범위 외 사유: Claude Code 아키텍처 제약
2. **87개 스킬 카테고리 초기 분류** — 현재 대부분 'general'(85개). 각 SKILL.md의 category 필드가 미설정. 범위 외 사유: 카테고리 기준 별도 정의 필요
3. **task-timers.json skill_list 필드** — 태스크별 사용 스킬 목록 기록 기능. 범위 외 사유: task-timer.py 수정 필요 (다른 팀 코드)
4. **deprecated 기준 미정** — 현재 description 내 'DEPRECATED' 문자열로 판단. 공식 기준 필요. 범위 외 사유: 제이회장님 별도 지시 대기

---

## 에이전트 미팅
- 1사이클 진행, 상세: `memory/meetings/task-1112.1-meeting.md` 참조
- 참석: 불칸, 이리스, 아테나, 아르고스, 로키(DA)
- 주요 합의: JSONL 로깅, REST API 수동 로깅, 대시보드 '스킬' 탭 신설

---

## 마아트 독립 검증

- 판정: **NEEDS WORK** → 수정 후 재검증 통과
- 발견 버그: 프론트엔드-백엔드 필드명 불일치 3건 (HIGH 2건, MEDIUM 1건) → 즉시 수정 완료
  - `call_count` → `count` (top_skills/by_team/by_date 차트)
  - `skill_name`/`name` → `skill_id` (Top 스킬 이름 표시)
  - 활성 스킬 `name` → `task_id`+`description` (활성 스킬 카드)
- 수정 후 pytest 6/6 재통과 확인

## QC 자동 검증 결과

```json
{
  "task_id": "task-1112.1",
  "overall": "5 PASS, 1 FAIL(보고서/done 미생성 시점), 6 SKIP",
  "test_runner": "PASS (6 passed)",
  "pyright_check": "PASS (0 errors)",
  "style_check": "PASS (black OK, isort OK)",
  "data_integrity": "PASS",
  "spec_compliance": "PASS"
}
```