# 워크플로우 분석 가이드

대상 스킬의 워크플로우 완성도를 분석하는 가이드입니다.

## 분석 대상

| 항목 | 검사 내용 |
|------|----------|
| 단계 명확성 | 각 단계가 명확하게 정의되어 있는지 |
| 분기 처리 | 조건 분기가 적절히 처리되어 있는지 |
| 실행 가능성 | 제시된 단계가 실제로 실행 가능한지 |
| 테스트 시나리오 | 검증 가능한 시나리오가 있는지 |

## 단계 명확성 검증

### 양호한 워크플로우 예시

```markdown
## Workflow

### Phase 1: 주제 선택
- 사용자 입력 파싱
- 범위 분석
- 너무 넓으면 → 사용자에게 초점 요청

### Phase 2: 소스 발견
- 각 하위 주제에 대해:
  1. 권위 있는 소스 검색
  2. 신뢰도 점수 산출
  3. 임계값 미달 시 재검색
```

### 부적절한 워크플로우 예시

```markdown
## Workflow
1. 분석한다
2. 개선한다
3. 완료한다
```

### 검사 기준

| 기준 | 양호 | 부적절 |
|------|------|--------|
| 단계 이름 | "주제 선택", "소스 발견" | "1단계", "분석" |
| 단계 설명 | 구체적 행동 명시 | 추상적 표현 |
| 입출력 | 명시됨 | 미명시 |
| 조건 분기 | if/then 명시 | 분기 없음 |

## 분기 처리 검증

### 분기 유형

| 유형 | 설명 | 예시 |
|------|------|------|
| 조건 분기 | 특정 조건에 따른 경로 분기 | "주제가 너무 넓으면 → 초점 요청" |
| 반복 분기 | 루프 처리 | "임계값 미달 시 → 재검색" |
| 예외 분기 | 오류/예외 상황 처리 | "파일 없음 → 에러 메시지" |

### 검사 항목

| 항목 | 검사 내용 |
|------|----------|
| 분기 존재 | 필수적인 분기가 명시되어 있는지 |
| 분기 조건 | 조건이 명확하게 정의되어 있는지 |
| 분기 결과 | 각 분기의 결과가 명시되어 있는지 |
| 루프 처리 | 반복 작업의 종료 조건이 있는지 |

## 실행 가능성 검증

### 검사 기준

| 기준 | 설명 |
|------|------|
| 도구 가용성 | 제시된 도구/명령어가 실제로 존재하는지 |
| 환경 요구사항 | 필요한 환경이 명시되어 있는지 |
| 권한 | 필요한 권한이 명시되어 있는지 |
| 데이터 가용성 | 필요한 데이터/입력이 확보 가능한지 |

### 일반적인 실행 불가 사례

| 사례 | 설명 |
|------|------|
| 존재하지 않는 명령어 | `git push --force-with-lease --all` (실제로는 `--force`) |
| 잘못된 경로 | `./scripts/old-name.sh` (실제로는 `./scripts/new-name.sh`) |
| 미구현 기능 | "LLM이 자동으로 판단한다" (구체적 로직 없음) |
| 환경 미명시 | "API 키가 필요하다" (어디서 obtained?)

## 테스트 시나리오 검증

### 검사 항목

| 항목 | 검사 내용 |
|------|----------|
| 테스트 존재 | 테스트 시나리오/예시가 있는지 |
| 시나리오 다양성 | 정상/예외/경계값 시나리오 포함 |
| 기대 결과 | 각 시나리오의 기대 결과가 명시 |
| 검증 가능 | 결과를 검증할 수 있는 기준이 있는지 |

## 점수 산출

| 항목 | 배점 | 감점 기준 |
|------|------|----------|
| 단계 명확성 | 30점 | 추상적 표현당 -5점 |
| 분기 처리 | 25점 | 필수 분기 누락 -10점 |
| 실행 가능성 | 25점 | 실행 불가 항목당 -10점 |
| 테스트 시나리오 | 20점 | 없음 -20점, 부족함 -10점 |

## 개선 패턴

### 패턴 1: 단계 추상화 개선

**현재:**
```markdown
### Phase 1: 분석
대상을 분석한다.
```

**개선:**
```markdown
### Phase 1: 대상 분석
1. SKILL.md 파일 읽기
2. Frontmatter 파싱
3. 섹션 구조 매핑
4. 참조 파일 목록 추출
```

### 패턴 2: 분기 처리 추가

**현재:**
```markdown
### Phase 2: 소스 발견
소스를 검색한다.
```

**개선:**
```markdown
### Phase 2: 소스 발견
1. 소스 검색
2. 신뢰도 점수 산출
3. 임계값(0.6) 이상 → 채택
4. 임계값 미달 → 대체 키워드로 재검색 (최대 3회)
5. 3회 미달 시 → 사용자에게 소스 부족 알림
```

### 패턴 3: 테스트 시나리오 추가

**현재:**
```markdown
## 사용 예시
```

**개선:**
```markdown
## 테스트 시나리오

| 시나리오 | 입력 | 기대 결과 |
|----------|------|-----------|
| 정상 | 유효한 SKILL.md 경로 | 개선 보고서 생성 |
| 예외 | 잘못된 경로 | 에러 메시지 + 경로 재요청 |
| 경계값 | 빈 SKILL.md | "파일이 비어 있습니다" 안내 |
```