# swing-skills 4종 학습 문서
> 작성일: 2026-03-17 | 작업: task-630.1

## 개요

- 설치된 4종: swing-trace, swing-mortem, swing-clarify, swing-options
- 설치 금지 2종 (사유):
  - swing-research: 사실 검증·외부 소스 조회 목적 — 내부 추론 분석 스킬과 역할 중복 없으나 현재 환경 미설치
  - swing-review: 현재 상태(코드·설계)의 결함 공격 — adversarial-review가 동일 역할 수행 중, 중복 설치 금지

---

## 1. swing-trace (추론 추적)

### 핵심 프로세스

- **Quick 모드 (기본)**: 3개 Stage만 실행
  - Stage 1 Claim Isolation: 복합 질문을 원자 단위 Claim으로 분해
  - Stage 2 Assumption Inventory: 각 Claim의 가정을 Criticality(High/Med/Low) + Verifiability(Direct/Indirect/Unverifiable) 2축으로 열거
  - Stage 5 Weakest Link: Criticality↑ + Verifiability↓ + Confidence↓ 교집합으로 최약 가정 1개 선정 → 대안 결론 도출

- **Full 모드 (--full)**: 5개 Stage 전체 실행 (Quick + 아래 2개 추가)
  - Stage 3 Decision Tree: 각 결정 분기점에서 선택 옵션·거부 이유·역전 조건 문서화
  - Stage 4 Confidence Decomposition: 전체 신뢰도를 3개 이상 독립 차원으로 분해 (각 %·증거유형·근거 명시), 가중평균으로 최종 신뢰도 산출

### 트리거 조건

description에서 추출한 트리거 키워드:
`왜 그렇게 생각해`, `reasoning`, `근거`, `show your work`, `어떻게 그 결론이`, `trace`, `판단 근거`, `why do you think that`

### 출력 포맷

**Quick 모드 출력 항목:**
- `## Reasoning Trace: [Claim]`
- `### Atomic Claims` — 분해된 원자 Claim 목록
- `### Assumption Inventory` — 테이블 (Assumption | Criticality | Verifiability)
- `### Weakest Link` — 최약 가정 + Why weakest + If wrong + How to verify

**Full 모드 추가 항목 (Quick + 아래):**
- `### Decision Forks` — 각 Fork별 선택/거부/역전조건
- `### Confidence Decomposition` — 차원별 % + 증거유형 + 근거 테이블 + Overall %
- `### Alternative Conclusion` — 최약 가정이 틀렸을 때 논리적 대안 결론
- `### Falsification Conditions` — 결론이 틀렸음을 증명하는 조건 목록

### 우리 시스템 활용 가이드

- **파이프라인**: deep-dive-analyzer → swing-trace → adversarial-review
  - deep-dive가 시스템 이해 → swing-trace가 추론 투명성 → adversarial-review가 스트레스 테스트
- **Lv.3+ 아키텍처 결정 시**: 반드시 swing-trace 사용 권장
  - Assumption Inventory로 숨겨진 전제 노출
  - Confidence Decomposition으로 판단 근거 정량화
  - Weakest Link으로 가장 큰 위험 요인 식별
- **agent-meeting 전 자료**: 의사결정 안건에 swing-trace 결과를 사전 준비하면 미팅 품질 향상
- **금지 조건**: 단순 사실 조회, 빠른 답변 요청 명시 시, 코드 전체 분석(→ deep-dive-analyzer 사용)

---

## 2. swing-mortem (사전 실패 분석)

### 핵심 프로세스 (6 Phase)

| Phase | 명칭 | 핵심 행동 |
|-------|------|-----------|
| 1 | Failure Frame 설정 | 시간축·주체 확정 후 "6개월 후 완전 실패" 선언문 작성 |
| 2 | Failure Scenario 생성 | 5개 카테고리(Technical/Organizational/External/Temporal/Assumption) 각 1개 시나리오 |
| 3 | Risk Matrix | Likelihood(H/M/L) × Impact(Catastrophic/Severe/Moderate) → Priority(P1~P4) |
| 4 | Leading Indicators | Top 3 리스크별 2-3개 조기 경보 (Measure·Threshold·Where·Lead time 명시) |
| 5 | Circuit Breakers | Top 3 리스크별 Trigger(측정 가능 임계값)·Fallback·Cost of delay·Decision owner |
| 6 | Pre-Mortem Summary | 최고 위험 + 조기 경보 지표 + 탈출구를 1문단으로 합성 (BLUF) |

**절대 규칙:**
- 시나리오에 특정 기술명·수치·타임라인 없으면 금지 ("DB가 느려질 수 있다" 형식 금지)
- 정확히 5개 카테고리, 각 1개 시나리오 (생략·중복 금지)
- Leading Indicator는 "intern test" 통과 필수 (신입도 임계값 초과 여부 판단 가능 수준)
- Phase 6 Pre-Mortem Summary 생략 금지

### 트리거 조건

description에서 추출한 트리거 키워드:
`리스크`, `위험`, `실패하면`, `swing-mortem`, `뭐가 잘못될 수 있어`, `risk`, `what could go wrong`, `걱정되는 점`, `failure modes`, `리스크 분석`, `위험 분석`

### 출력 포맷

핵심 섹션 구조:
- `### Failure Frame` — 실패 선언문
- `### Failure Scenarios` — Scenario 1~5 (What happened / Why plausible / Consequence)
- `### Risk Matrix` — 5행 테이블 (Category | Scenario | Likelihood | Impact | Priority)
- `### Deep Analysis (Top 3 Risks)` — Leading Indicators + Circuit Breaker (각 Risk 반복)
- `### Pre-Mortem Summary` — 단락형 BLUF

### 우리 시스템 활용 가이드

- **pdp-agent Risk Phase와의 역할 경계**:
  - pdp-agent Risk (Step 4~5): UX/기술/비즈니스 체크리스트 기반 항목별 LOW/MEDIUM/HIGH/CRITICAL 판정 → GO/HOLD/NO-GO 의사결정 도구 (빠른 판정)
  - swing-mortem: 5 카테고리 심층 시나리오 + 측정 가능 Leading Indicator + Circuit Breaker (깊은 분석)
  - **사용 시점 구분**: pdp-agent Risk는 "개발 착수 여부(Go/No-Go)", swing-mortem은 "착수 후 또는 주요 의사결정 전 실패 시나리오 상세 분석"
  - pdp-agent Risk Phase에서 HIGH/CRITICAL 리스크 발견 시 → swing-mortem으로 상세 분석 위임 가능

- **pdp-agent에서 호출 포인트**:
  - Step 5 RFE (킥오프 전 전체 스캔) → 고위험 항목 발견 시 swing-mortem 호출
  - Kill Metric 설정 시 swing-mortem의 Leading Indicators + Circuit Breakers를 참조하면 정밀도 향상

- **활용 적합 시점**: 프로젝트 계획 확정 전, 비가역적 아키텍처 결정 전, 신기술 프로덕션 도입 전, 주요 기능 런칭 전
- **활용 부적합 시점**: 현재 코드 결함 탐색(→ adversarial-review), 옵션 비교(→ swing-options), 일상 코드 리뷰

---

## 3. swing-clarify (명확화 방화벽)

### 핵심 프로세스 (4 Stage)

| Stage | 명칭 | 핵심 행동 |
|-------|------|-----------|
| 1 | 5W1H Decomposition | What/Who/Where/When/Why/How 6개 차원으로 요청 분해 |
| 2 | Ambiguity Scoring | 각 차원을 Clear/Assumable/Ambiguous로 분류, Ambiguous 수 집계 |
| 3 | Clarifying Questions 생성 | Ambiguous 0개→즉시 진행, 1-2개→1-2개 질문, 3개+→최대 3개 질문 (다지선다·기본값 명시) |
| 4 | Confirm and Proceed | 답변 수신 후 확정 범위 3-5개 불릿으로 재진술 → 실행 |

**절대 규칙:**
- 최대 3개 질문 (초과 시 요청 분해 먼저)
- 모든 질문에 기본값(default) 명시 필수
- 다지선다 형식 우선 (개방형 질문 지양)
- 명확한 요청에 불필요한 질문 금지
- 스타일·네이밍·폴더구조는 scope 질문 대상 아님

### 트리거 조건

description에서 추출한 트리거 키워드:
`뭘 원하는건지`, `요구사항 정리`, `clarify`, `what exactly`, `scope`, `requirements`, `정확히 뭘`, `before we start`

### 출력 포맷

핵심 섹션 구조:
- `## Scope Analysis: [Request Summary]`
- `### 5W1H Decomposition` — 6차원 테이블 (Dimension | Status | Detail)
- `### Ambiguity Score: N/6 → [판정]`
- `### Questions` — Q1~Q3 (질문 + Options + My default + Impact)
- `### Clarified Scope` — 확정된 범위 불릿
- `### Remaining Assumptions` — Assumable로 분류된 항목 목록

### 우리 시스템 활용 가이드

- 모든 비정형 작업 접수 시 scope 명확화에 활용 (가장 먼저 실행)
- agent-meeting, project-kickoff 선행 절차로 활용 가능
- swing-trace, swing-mortem, swing-options 실행 전 입력 품질 보장에 활용
  - swing-clarify → swing-trace: Stage 1 Claim Isolation 품질 향상
  - swing-clarify → swing-mortem: Phase 1 Failure Frame 구체화
  - swing-clarify → swing-options: 제약 조건 확정으로 Unconventional 경계 명확화
- **사용 제외 조건**: 재현 단계가 있는 버그 리포트, 상세 스펙이 명시된 요청, 진행 중 대화의 후속 작업

---

## 4. swing-options (대안 생성)

### 핵심 프로세스 (5 Step)

| Step | 명칭 | 핵심 행동 |
|------|------|-----------|
| 1 | Input Clarity 검증 | 결정 명확성·제약 조건 파악, 불명확 시 1개 질문 |
| 2 | Decision Space 프레이밍 | 결정 대상·제약·"명백한 답" 식별 (도전 대상 설정) |
| 3 | Options 생성 (Distribution-First) | 5개 옵션을 확률 분포 전체에서 샘플링 |
| 4 | 각 Option 분석 | What + Best FOR + Best AGAINST + Best suited when + Effort 5항목 |
| 5 | Hidden Assumptions 노출 | 관습적 선택의 전제 명시 + 전제 깨질 경우 우선 옵션 변경 |

**확률 존 분류 (5개 옵션 분포 기준):**
- Conventional (p > 40%): 대부분이 선택할 "명백한" 옵션
- Mainstream (p 20-40%): 흔히 고려되는 대안
- Uncommon (p 10-20%): 유효하지만 간과되는 옵션
- Unconventional (p 5-10%): 전제에 도전하는 옵션
- Wild card (p < 5%): 문제 재프레이밍 수준의 급진적 옵션

**절대 규칙:**
- 정확히 5개 옵션 (사용자 지정 시 존중)
- Unconventional 또는 Wild card 최소 1개 포함 필수
- 추천 금지 (모든 옵션을 동등하게 제시)
- 각 옵션에 구체적 Trade-off 분석 필수
- 유사 변형(MariaDB vs MySQL 등) 으로 채우는 False Diversity 금지

### 트리거 조건

description에서 추출한 트리거 키워드:
`대안`, `alternatives`, `옵션 뽑아`, `options`, `어떤 방법이`, `아이디어`, `다른 방법`, `선택지`

### 출력 포맷

핵심 섹션 구조:
- `## Decision: [결정 질문]`
- `### Constraints` — 제약 조건 목록
- `### Options` — Option 1~5 (각: 확률존 + 설명 + 분석 테이블)
- `### Hidden Assumptions` — 관습 선택의 전제 + 전제 변경 시 재고 옵션
- `### Decision Matrix` — 기준별 Strong/Moderate/Weak 평가 (사용자 제약 3-5개 + Hidden criterion 1개)

### 우리 시스템 활용 가이드

- **agent-meeting의 UAM(Universal Action Model)과 보완적 사용**: 미팅 밖 독립 의사결정 시 swing-options 사용, 미팅 내 다자간 합의 시 UAM 프로세스
- **swing-mortem → swing-options 연계**: swing-mortem에서 High Priority 리스크 식별 후 → 해당 리스크를 회피하는 대안 경로를 swing-options로 탐색
- **pdp-agent Planning 단계 연계**: 기능 설계 옵션 분기점에서 swing-options로 대안 다양성 확보
- **사용 제외 조건**: 정답이 하나인 사실 질문, 이미 결정된 사항의 실행, 단순 구현 (방법이 자명한 경우)

---

## 5. 통합 파이프라인 가이드

### 추천 파이프라인 조합

1. **아키텍처 결정 파이프라인** (Lv.3+ 의사결정):
   ```
   swing-clarify → deep-dive-analyzer → swing-trace → adversarial-review
   ```
   - swing-clarify: 결정 범위 확정
   - deep-dive-analyzer: 현재 시스템 전체 이해
   - swing-trace: 추론 체인 투명화 (가정 인벤토리 + 최약 가정)
   - adversarial-review: 최약 가정 기반 스트레스 테스트

2. **리스크 분석 파이프라인** (신기술 도입·주요 기능 런칭 전):
   ```
   swing-clarify → swing-mortem → swing-options → (대안 선택)
   ```
   - swing-clarify: 분석 범위·가정 확정
   - swing-mortem: 5 카테고리 실패 시나리오 + Circuit Breaker
   - swing-options: 고위험 시나리오 회피 대안 생성

3. **빠른 의사결정 파이프라인** (Lv.1-2, 가역적 결정):
   ```
   swing-clarify → swing-options
   ```
   - swing-clarify: 제약 조건 명확화
   - swing-options: 확률 분포 전체에서 옵션 샘플링

4. **pdp-agent 연계 파이프라인** (기능 개발 전체 사이클):
   ```
   pdp-agent Planning → swing-clarify → pdp-agent Risk →
   (HIGH/CRITICAL 시) swing-mortem → swing-options → pdp-agent Build
   ```

### 기존 스킬과의 관계 맵

| swing-skill | 연계 스킬 | 연계 방향 | 관계 유형 |
|-------------|-----------|-----------|-----------|
| swing-clarify | 모든 swing-skills | swing-clarify → (다음 스킬) | 선행 필터 |
| swing-clarify | agent-meeting | 선행 절차 | 직렬 선행 |
| swing-trace | deep-dive-analyzer | deep-dive → swing-trace | 이해 → 추론 |
| swing-trace | adversarial-review | swing-trace → adversarial | 노출 → 공격 |
| swing-trace | swing-options | swing-options → swing-trace | 대안 → 추론 검증 |
| swing-mortem | pdp-agent Risk | Risk HIGH → swing-mortem | 빠른 판정 → 상세 분석 |
| swing-mortem | swing-options | swing-mortem → swing-options | 실패 식별 → 대안 탐색 |
| swing-mortem | deep-dive-analyzer | deep-dive → swing-mortem | 이해 → 위험 예측 |
| swing-options | agent-meeting UAM | 보완 (미팅 밖 독립 사용) | 역할 분리 |
| swing-options | pdp-agent Planning | Planning → swing-options | 기획 → 대안 확보 |