Socsci Paper Orchestrator

---
name: socsci-paper-orchestrator
description: "사회과학 학술논문을 에이전트 팀으로 작성하는 오케스트레이터. 연구주제·메모·데이터·선행연구를 받아 연구설계→설계검토 게이트→근거조사·데이터분석→집필→다관점 검수→Word(.docx)·Markdown 변환까지 6인 팀(paper-designer, paper-investigator, paper-analyst, paper-writer, paper-reviewer, paper-finalizer)을 조율한다. OmO식 2단계 검증(집필 전 설계 게이트 + 집필 후 5축 검수)이 핵심. '사회과학 논문', '학술논문 작성', '논문 초안', '학위논문', '논문 작성', '연구논문', '실증연구', '질적연구', '가설 설계', '논문 검수' 요청 시 반드시 사용. 후속 작업: 논문 수정, 부분 재실행, 업데이트, 보완, 다시 작성, 특정 장만 다시(서론·이론·방법·결과·논의·결론), 설계 다시, 목차 검토·승인, 가설 재설계, 데이터 재분석, 분량 늘리기, 참고문헌 정리·출처 검증, 검수 다시, 근거 보강, 기존 초안·데이터 기반 작성/개정, docx만 다시 생성, 이전 결과 기반 개선 요청 시에도 반드시 이 스킬을 사용. ※ 정부 R&D '제안서/연구개발계획서'는 rnd-proposal-orchestrator, '정책연구보고서'는 rnd-policy-research-orchestrator를 사용."
---

# 사회과학 논문 오케스트레이터

실제 사회과학 연구를 6인 에이전트 팀으로 수행해 학술논문(.docx + .md)을 산출한다. OmO(oh-my-openagent)의 핵심 패턴인 **2단계 검증 게이트**(집필 전 설계 검토 + 집필 후 5축 검수)를 이식했다.

## 실행 모드: 에이전트 팀

## 에이전트 구성

| 팀원 | 타입 | 역할 | 스킬 | 출력 |
|------|------|------|------|------|
| paper-designer | paper-designer | 의도분석 + RQ·가설·이론틀·연구방법·목차 설계 | paper-design | `01_research_design.md` |
| paper-reviewer | paper-reviewer | (모드1) 설계 게이트 / (모드2) 5축 초안 검수 | paper-review | `02_design_review.md`, `05_draft_review.md` |
| paper-investigator | paper-investigator | 선행연구(SLR)·이론출처·통계·사례 조사, 출처 병기 | paper-research | `03_literature.md` |
| paper-analyst | paper-analyst | 데이터분석 — 양적·질적·혼합 (조건부) | paper-analysis | `03b_data_analysis.md` |
| paper-writer | paper-writer | 본문 집필 (서론→이론→방법→결과→논의→결론) + 참고문헌 | paper-writing | `04_paper_draft.md` |
| paper-finalizer | paper-finalizer | 한국어 교정교열 + docx/md 변환 | paper-proofread + docx | `06_paper.docx`, `06_paper.md` |

모든 팀원은 기본적으로 세션 모델을 상속해 스폰한다(품질 우선 시 `model: "opus"` — 공개판 실행 노트 참조). 검토관(reviewer)은 파이프라인에서 **두 번** 등판한다(설계 후·초안 후). **paper-analyst는 조건부** — 실증연구(양적/질적/혼합)면 투입, 데이터 없는 이론·문헌 연구면 이 단계를 건너뛴다.

## 워크플로우

### Phase 0: 컨텍스트 확인 (후속 작업 지원)

작업 디렉토리의 `_workspace/` 존재 여부로 실행 모드를 결정한다:
- **`_workspace/` 미존재** → 초기 실행. Phase 1로.
- **`_workspace/` 존재 + 부분 수정 요청** (예: "설계 다시", "논의 장만 다시", "데이터 재분석", "근거 보강", "검수 다시", "docx만 재생성") → 부분 재실행. 해당 에이전트만 재호출하고 그 산출물만 갱신한다. 의존 산출물(설계 변경 시 → 조사·분석·집필·검수도 영향)을 함께 갱신할지 판단한다.
- **`_workspace/` 존재 + 새 주제/새 입력** → 새 실행. 기존 `_workspace/`를 `_workspace_{YYYYMMDD_HHMMSS}/`로 이동 후 Phase 1로.

부분 재실행 시 이전 산출물 경로를 해당 에이전트 프롬프트에 포함해, 기존 결과를 읽고 피드백을 반영하도록 지시한다.

### Phase 1: 준비 (입력 수집 + 자료 라우팅 + 연구유형 판별)
1. 사용자 입력 분석 — 연구 주제, RQ 단서, 메모, **기존 초안·선행연구·데이터셋·통계**, 방법론(양적/질적/혼합/이론), 목표 산출물(학위논문/저널·분량), 출력 경로, 인용형식(기본 APA7)을 파악한다.
2. `_workspace/` 생성 (새 실행이면 기존 것을 타임스탬프 디렉토리로 이동 후 재생성).
3. **입력 자료 저장 + 인덱싱** — 사용자가 준 모든 자료를 `_workspace/00_input/`에 저장하고, `_workspace/00_input/_index.md`에 "파일명 — 성격(초안/데이터/선행연구/메모) — 어느 단계·에이전트가 쓸지"를 한 줄씩 기록한다. 이 인덱스가 라우팅의 핵심이다.
   - **자료 라우팅 규칙:** 주제·범위 단서 → designer / 선행연구·이론출처·통계 → investigator / **데이터셋** → analyst / **기존 초안** → writer(베이스로 개정) + reviewer(검수 대상) / 인용형식·템플릿 → finalizer.
   - **기존 초안 제공 시:** 백지 집필이 아니라 그 초안을 출발점으로 삼는다. designer는 초안 구조를 분석해 RQ·가설·목차를 역설계·보완하고, investigator는 초안 주장의 출처를 검증·보강하며, writer는 초안을 개정한다. 이 분기를 각 에이전트 프롬프트에 명시한다.
4. **연구유형 판별(잠정)** — 데이터 유무·방법론으로 paper-analyst 투입 여부를 잠정 결정한다(최종 확정은 Phase 3 설계에서). 이론·문헌 연구면 분석 단계를 건너뛸 계획을 세운다.

### Phase 2: 팀 구성
1. `TeamCreate(team_name: "socsci-paper-team", members: [...])` — 위 팀원을 각 에이전트 정의(custom type)로로 스폰한다. 이론·문헌 연구로 확정되면 paper-analyst는 제외할 수 있다. 각 프롬프트에 담당 스킬명·`_workspace/` 경로·입출력 파일·docx 출력 경로(`04_paper_draft.md`→`06_paper.docx`)·인용형식을 명시한다.
2. `TaskCreate`로 의존성 있는 작업을 등록한다:
   - T1 연구설계 (designer)
   - T2 **설계 검토 게이트** (reviewer 모드1) — `depends_on: [T1]`
   - T3 근거조사 (investigator) — `depends_on: [T2 승인]`
   - T3b 데이터분석 (analyst, **조건부**) — `depends_on: [T2 승인]` (T3와 병렬)
   - T4 집필 (writer) — `depends_on: [T2 승인, T3, (T3b)]`
   - T5 초안검수 (reviewer 모드2) — `depends_on: [T4]`
   - T6 교정·변환 (finalizer) — `depends_on: [T5 승인]`

### Phase 3: 설계 + 게이트 (생성-검증 루프 ①)
**실행 방식:** designer ↔ reviewer(모드1) 피드백 루프

1. designer가 의도분석 + RQ·가설(변수·조작적정의)·이론틀·연구방법·목차를 설계해 `01_research_design.md`를 작성한다.
   - **사용자 확인 질문이 나오면** 리더가 사용자에게 전달하고 답을 받아 designer에 반영시킨다(조사·집필 착수 전에). 특히 **데이터 확보 가능성**·방법론·범위를 명확히 한다.
2. designer가 reviewer에게 "설계 검토 요청"을 SendMessage로 보낸다.
3. reviewer(모드1)가 `01`을 검토해 `02_design_review.md`에 **VERDICT(GO/조건부/NO-GO)**를 쓴다.
4. NO-GO·조건부면 designer가 `01`을 개정 → 재검토. **최대 2회.** 2회 후에도 미승인 항목은 "설계 잔여 리스크"로 기록하고 진행한다.
5. **★ 목차 사용자 승인 게이트 (필수)** — 설계 게이트를 통과하면, 리더는 **목차(장·절) + 핵심 RQ·가설 + 연구방법 요약**을 사용자에게 제시하고 승인을 받는다. (검토관 게이트는 "실행 가능성"을, 이 게이트는 "사용자 의도 부합"을 본다.)
   - 사용자가 목차·가설·방법을 수정하면 designer가 `01`에 반영 후 다시 제시한다.
   - **사용자 승인(또는 명시적 "그대로 진행") 전에는 Phase 4로 넘어가지 않는다.** RQ·가설 한 줄이 며칠치 조사·분석·집필을 좌우하므로 이 게이트가 비싼 헛작업을 막는다.
6. **설계 게이트 통과 + 사용자 목차 승인 후에만** Phase 4로 넘어간다. 이 시점에 **연구유형이 확정**되어 paper-analyst 투입 여부가 결정된다.

### Phase 4: 근거조사 ∥ 데이터분석 (병렬)
**실행 방식:** investigator + analyst 병렬 (analyst는 조건부)

1. designer가 승인 목차의 항목별 "조사 우선순위·필요근거"를 investigator에게, "분석할 데이터·변수·가설·기법"을 analyst에게 전달한다.
2. investigator가 선행연구·이론출처·통계·사례를 조사해 `03_literature.md`에 출처와 함께 정리한다(미확보 항목은 "[미확보]").
3. **(실증연구만)** analyst가 데이터 무결성을 점검하고 가설을 검증해 `03b_data_analysis.md`에 결과·표·그림·한계를 정리한다. 데이터가 없거나 이론·문헌 연구면 이 단계를 건너뛴다.
4. 두 작업 완료 시 writer에게 알린다.

### Phase 5: 집필 + 검수 (생성-검증 루프 ②)
**실행 방식:** writer ↔ reviewer(모드2) 피드백 루프

1. writer가 `01`(승인 설계)·`03`(근거)·`03b`(분석, 있으면)·`00_input/`(기존 초안 있으면 베이스로)을 종합해 `04_paper_draft.md`를 작성한다.
   - **표준 목차:** 1.서론 → 2.이론적 배경·선행연구 → 3.연구방법 → 4.분석결과 → 5.논의 → 6.결론 → **참고문헌**(말미). (사용자 승인 목차가 우선. 이론·문헌 연구는 3·4장을 쟁점별 논증으로 변형.)
   - **인용·참고문헌 필수:** 본문 인용 ↔ 참고문헌 1:1, 지정 형식(기본 APA7) 일관 적용. 출처 없는 주장 금지, 미확보는 `[보강 필요]`.
2. reviewer(모드2)가 `04`를 `01`·`03`·`03b`와 교차검증해 **5축(①RQ·가설 충족 ②근거·출처 무결성 ③논리 정합성 ④방법론 타당성 ⑤한국어 교열)**으로 `05_draft_review.md`에 수정 요청을 쓴다.
   - **출처 검증:** 본문 인용 ↔ 참고문헌 일치, 각 출처의 실재·접근성(URL/DOI/KCI 식별자), 인용 수치와 출처 내용 일치, 환각 출처 플래그.
3. writer가 [필수]·[권고] 지적을 반영해 `04`를 개정한다. **최대 2회 반복.** 동일 항목 2회 미해결은 "잔여 리스크"로 기록하고 진행.
   > **운영 유의(검증된 제약):** 백그라운드로 재개(SendMessage)된 서브에이전트는 Write/Edit 권한이 거부될 수 있다. writer 수정 루프는 **전경(foreground) Agent 호출**로 실행하거나, reviewer가 승인한 비창작성 수정안을 **리더가 직접 Edit로 반영**한다. 사용자 입력이 필요한 항목은 `[보강 필요]`로 남긴다.
4. 검수 통과 시 reviewer가 "초안 승인"을 리더와 paper-finalizer에게 알린다.

### Phase 6: 교정·변환
**실행 방식:** 승인 후 finalizer

1. finalizer가 승인된 `04_paper_draft.md`를 입력으로 받는다.
2. `paper-proofread` 스킬로 한국어 교정교열(맞춤법·문장·인용 정합)을 수행하고 `06_proofread_log.md`에 교정 내역을 남긴다.
3. `docx` 스킬로 `.docx`를 생성한다(제목·초록·본문·표·그림·참고문헌 구조 보존). Markdown 사본도 둔다.
4. 변환 후 재검토(표·그림·인용 보존, `[보강 필요]` 잔존 여부 점검).
5. 최종 산출물을 사용자 지정 경로에 `{제목}.docx`로, 사본을 `_workspace/06_paper.docx`·`06_paper.md`에 저장한다.

### Phase 7: 정리·보고
1. 팀원에게 종료 요청(SendMessage) 후 `TeamDelete`.
2. `_workspace/`는 보존한다 (사후 검증·재실행용).
3. 사용자에게 요약 보고: 최종 .docx/.md 경로, RQ에 대한 답·가설 지지여부 요약, 핵심 발견, 잔여 리스크·`[보강 필요]`·미확보 근거·데이터 한계.
4. 피드백을 요청한다 ("수정하거나 보완할 부분이 있나요?").

## 데이터 흐름

```
[리더] TeamCreate + TaskCreate
  paper-designer ──01_research_design.md──┐
        ▲  │ SendMessage(설계 검토 요청)   │
   (개정,최대2회) ▼                        ▼
  paper-reviewer(모드1) ──02_design_review.md (게이트)
        │ "설계 승인" → ★목차 사용자 승인
        ▼  (승인 후에만 진행 · 연구유형 확정)
  ┌─────────────────────┬───────────────────────┐
  paper-investigator     paper-analyst (조건부)
   ──03_literature.md     ──03b_data_analysis.md
  └─────────┬───────────────────┬───────────────┘
            ▼ (병합)
       paper-writer ──04_paper_draft.md──┐
            ▲  │                          │
  SendMessage(수정요청) │ (최대 2회 루프)   ▼
       paper-reviewer(모드2, 5축) ──05_draft_review.md
            │ "초안 승인"                  │
            ▼                             │
       paper-finalizer ◀──────04 승인본────┘
        (paper-proofread + docx)
            │
            ▼
       06_paper.docx + .md → 사용자 지정 경로
```

## 에러 핸들링

| 상황 | 전략 |
|------|------|
| 팀원 1명 실패/중지 | 리더가 감지 → SendMessage로 상태 확인 → 재시작. 실패 시 해당 산출물 없이 진행하고 논문에 누락 명시 |
| 설계 게이트 무한 반려 | 동일 항목 2회 초과 미해결 → "설계 잔여 리스크"로 기록 후 진행. NO-GO는 차단이 아니라 수정 지시 |
| 데이터 없음/부적합 | analyst가 "[데이터 필요]"·한계 명시 → 이론·문헌 연구로 전환하거나 writer가 `[보강 필요]` 표시 |
| 근거 미확보 | investigator "[미확보]" 명시 → writer `[보강 필요]` → 논문·최종보고에 명시 |
| 초안 검수 무한 루프 | 동일 항목 2회 초과 미해결 → 잔여 리스크로 기록 후 진행 |
| 상충 근거 | 출처 병기, 삭제 금지. reviewer가 판단·권고 |
| 사용자 확인 질문 미응답 | 합리적 기본값으로 가정하고 "가정 사항"으로 명시, 진행 |
| docx 변환 실패 | Markdown 우선 제공, 수동 변환 안내 |
| 백그라운드 Write/Edit 거부 | writer 수정 루프를 전경 호출로 전환 또는 리더가 직접 Edit 반영(Phase 5 유의 참조) |

## 테스트 시나리오

### 정상 흐름 (실증-양적)
1. 사용자가 "사회적 자본이 청년 정치참여에 미치는 영향" 주제 + 설문 데이터(.xlsx) 제공
2. Phase 1: `_workspace/` 생성, 데이터를 analyst로 라우팅, 연구유형=양적 잠정 판별
3. Phase 2: 6인 팀 + 작업(게이트 의존성) 등록
4. Phase 3: designer가 RQ 1개·가설 2개(변수·조작적정의)·이론틀(사회자본론)·회귀분석 설계 → reviewer 모드1이 "매개변수 측정 불명확" 조건부 → designer 개정 → GO → ★사용자 목차 승인
5. Phase 4: investigator가 선행연구·이론출처 조사 ∥ analyst가 신뢰도 점검 후 위계적 회귀
6. Phase 5: writer 초안 → reviewer 모드2가 [필수]2(과대해석·유령인용)·[권고]3 지적 → writer 반영 → 승인
7. Phase 6: 교정 후 .docx 생성, 표·인용 보존 확인
8. Phase 7: 지정 경로에 `청년정치참여_논문.docx` + RQ 답·가설 지지여부 보고

### 에러 흐름 (이론·문헌 연구로 전환)
1. 사용자가 실증 주제를 줬으나 데이터 미보유로 확인됨
2. Phase 3 설계에서 이론·문헌 연구로 전환, paper-analyst 제외
3. 목차 3·4장을 쟁점별 논증으로 변형, 사용자 승인
4. Phase 4는 investigator 단독, Phase 5에서 데이터 기반 주장은 `[보강 필요]`
5. 최종 보고에 "실증 검증은 후속 데이터 수집 후 권장" 명시

## 공개판 실행 노트 (플러그인 배포판)

- **에이전트 이름 네임스페이스** — 플러그인으로 설치하면 에이전트 타입이 `<플러그인명>:<에이전트명>`(예: `policy-research-kit:policy-research-designer`)으로 표시될 수 있다. 이 문서의 에이전트명은 접미 이름 기준이며, 실제 스폰 시에는 현재 세션의 에이전트 목록에 표시되는 이름을 그대로 쓴다.
- **팀 API 폴백 (중요)** — `TeamCreate`/`TaskCreate`/팀 `SendMessage`(에이전트 팀 실험 기능)가 없는 환경에서는 같은 파이프라인을 **전경(foreground) `Agent` 호출의 순차 실행**으로 수행한다. Phase 순서(설계→게이트→조사→집필→검수→변환)와 산출물 파일 계약은 동일하며, 이 폴백은 실전 검증된 방식이다. 특히 수정 루프는 전경 실행을 권장한다(백그라운드로 재개된 서브에이전트는 Write/Edit가 거부될 수 있음 — 이 경우 리더가 승인된 수정안을 직접 반영).
- **모델** — 기본은 세션 모델 상속(`model: inherit`). 품질을 우선하려면 스폰 시 `model: "opus"` 등 상위 모델을 명시한다.
- **한글(.hwpx) 변환 의존성** — hwpx 산출은 kordoc MCP(제3자, `npx kordoc@latest mcp`)에 의존한다. 미설치 환경에서는 마크다운/docx 산출까지 진행하고 변환 단계만 보류하면 된다.