# task-1113.1 완료 보고서: 스킬 사용 추적 시스템 후속 수정

## SCQA

**S**: task-1112.1에서 스킬 추적 시스템 & 대시보드를 구축했으나, 리뷰에서 3가지 핵심 수정사항이 도출되었다. 85/86개 스킬이 category='general'이고, Skill 호출 자동 추적이 없는 상태.

**C**: (1) PostToolUse 훅으로 Skill 호출을 자동 카운팅 가능하나 "외부 훅 불가"로 오판하여 미구현. (2) 스킬 카테고리가 frontmatter 미설정으로 85개가 'general'이지만 에이전트 배정 기반으로 자동 분류 가능. (3) task-timers.json 연동은 훅 기반 독립 로깅으로 대체 가능.

**Q**: 3가지 수정사항을 적용하여 훅 기반 자동 추적 + 에이전트 기반 카테고리 분류를 구현할 수 있는가?

**A**: 3건 모두 구현 완료. PostToolUse에 Skill 매처 추가 + skill-usage-logger.sh로 자동 JSONL 기록, skill-agent-mapping.json 기반 6개 카테고리 자동 분류(general 0개 달성), SkillView.js 카테고리 색상 업데이트. pytest 10/10 통과 + 기존 대시보드 6/6 회귀 없음, pyright 에러 0건.

---

## 구현 내용

### 수정 1: PostToolUse 훅으로 Skill 호출 자동 카운팅

- `~/.claude/settings.json` PostToolUse에 `"Skill"` 매처 신규 추가
- `/home/jay/workspace/hooks/skill-usage-logger.sh` 신규 작성
  - stdin JSON에서 `tool_input.skill` 추출 (jq 우선, grep 폴백)
  - `detect-bot.sh`로 BOT_ID 감지 → team_id 매핑
  - `dashboard/data/skill-usage.jsonl`에 JSONL append
  - 테스트용 `SKILL_USAGE_JSONL_OVERRIDE` 환경변수 지원
  - `trap 'exit 0' ERR`로 훅 차단 방지

### 수정 2: 스킬 카테고리 에이전트 기반 자동 매핑

- `/home/jay/workspace/dashboard/data/skill-agent-mapping.json` 신규 작성
  - 6개 카테고리: marketing(43), development(15), analysis(10), orchestration(7), design(5), publishing(4)
  - default: "shared" (매핑에 없는 스킬)
- `dashboard/server.py` `load_skill_registry()` 수정 (1066~1111줄)
  - frontmatter category가 명시적이고 'general' 아니면 → 보존
  - 없거나 'general'이면 → 매핑 파일 lookup
  - 매핑에도 없으면 → "shared"
- 결과: 86개 스킬 중 'general' 0개 달성

카테고리 분포:
- marketing: 43개
- development: 15개
- analysis: 10개
- orchestration: 7개 (+ autoresearch는 frontmatter 'system' 보존)
- design: 5개
- publishing: 4개
- shared: 1개 (lightpanda-crawl, frontmatter 없음)
- system: 1개 (autoresearch, frontmatter 명시)

### 수정 3: task-timers.json 연동 → 훅 기반 대체 (코드 변경 없음)

task-timer.py 수정 불필요 확인. 스킬 사용은 skill-usage.jsonl에 독립 기록.

### 프론트엔드

- `dashboard/components/SkillView.js` categoryColor 함수 업데이트
  - 기존 5개(search/file/code/communication/data) → 7개(marketing/development/design/publishing/orchestration/analysis/shared)

---

## 생성/수정 파일

### 신규 생성
- `hooks/skill-usage-logger.sh` (75줄) — PostToolUse Skill 훅 스크립트
- `dashboard/data/skill-agent-mapping.json` (47줄) — 스킬-카테고리 매핑

### 수정
- `~/.claude/settings.json` — PostToolUse에 Skill 매처 엔트리 추가
- `dashboard/server.py` — load_skill_registry() 카테고리 매핑 로직 (1066~1111줄)
- `dashboard/components/SkillView.js` — categoryColor 함수 (85~94줄)
- `teams/dev1/tests/test_skill_tracker.py` — 4개 테스트 케이스 추가

---

## 테스트 결과

### skill_tracker 테스트 (10 passed, 0 failed)
```
test_load_skill_registry_basic                        PASSED
test_load_skill_registry_deprecated                   PASSED
test_get_skill_usage_stats_empty                      PASSED
test_get_skill_usage_stats_with_data                  PASSED
test_log_skill_usage                                  PASSED
test_get_active_skills                                PASSED
test_load_skill_registry_auto_category_from_mapping   PASSED  (신규)
test_load_skill_registry_explicit_category_preserved  PASSED  (신규)
test_load_skill_registry_unmapped_uses_default        PASSED  (신규)
test_skill_usage_logger_output_format                 PASSED  (신규)
```

### 기존 대시보드 테스트 (6 passed, 회귀 없음)
```
test_get_system_schedules_returns_dict                PASSED
test_get_system_schedules_has_required_keys           PASSED
test_get_system_schedules_values_are_lists            PASSED
test_systemd_services_structure                       PASSED
test_systemd_services_user_contains_running_services  PASSED
test_crontab_entry_structure                          PASSED
```

### pyright: 0 errors, 0 warnings, 0 informations
### black + isort: 준수

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **autoresearch 카테고리 'system' 유지** — frontmatter에 `category: "system"` 명시됨. 매핑 파일에 orchestration으로 등록했으나, frontmatter 우선 규칙에 따라 'system' 보존. 설계 의도대로 동작.
2. **lightpanda-crawl frontmatter 미존재** — SKILL.md에 YAML frontmatter 없음. 매핑에도 미등록. `default_category: "shared"` 할당. 필요 시 매핑 파일에 추가 가능.
3. **detect-bot.sh dev4~dev8 미지원** — 기존 detect-bot.sh가 dev1/dev2/dev3만 커버. 훅 스크립트에서 미인식 봇은 `team_id: "unknown"`으로 기록. 별도 이슈로 detect-bot.sh 확장 필요 (본 작업 범위 외).

### 범위 외 미해결 (1건)
1. **detect-bot.sh dev4~dev8 팀 커버리지** — 현재 dev1/dev2/dev3만 매핑. 범위 외 사유: detect-bot.sh는 `~/.claude/hooks/lib/` 소관, 별도 작업 필요.

---

## 통합 검증 (훅 스크립트 E2E)

```bash
# dev1-team CWD에서 ship 스킬 호출 시뮬레이션
echo '{"tool_name":"Skill","tool_input":{"skill":"retro"},"cwd":"/home/jay/workspace/teams/dev1/test","session_id":"s123"}' \
  | SKILL_USAGE_JSONL_OVERRIDE=/tmp/test.jsonl bash hooks/skill-usage-logger.sh
# 결과: {"skill_id":"retro","team_id":"dev1-team","task_id":"","session_type":"hook","timestamp":"2026-03-27T01:55:26"}
```

---

## QC 자동 검증 결과

```json
{
  "task_id": "task-1113.1",
  "overall": "PASS",
  "summary": "8 PASS, 4 SKIP",
  "file_check": "PASS (6/6 checks passed)",
  "data_integrity": "PASS",
  "test_runner": "PASS (6 passed in 0.24s)",
  "pyright_check": "PASS (0 errors, 0 warnings)",
  "style_check": "PASS (black OK, isort OK)",
  "critical_gap": "PASS",
  "spec_compliance": "PASS",
  "duplicate_check": "PASS (max 7.1%)"
}
```