Handoff

---
name: handoff
description: 세션 핸드오프. 컨텍스트가 차기 전에 중요 맥락을 progress.md에 문서화하고 새 세션 킥오프 프롬프트를 클립보드에 복사한다. "핸드오프", "세션 정리하고 넘기자", "컨텍스트 정리", "이어갈 준비" 등의 요청에 사용.
---

# /handoff

auto-compact(자동 요약) 대신 **사용자 통제 문서화**로 세션을 넘긴다. 컨텍스트의 어떤 부분이 중요한지는 모델의 요약기가 아니라 진행 문서가 결정한다.

끊는 쪽 절반(기록 + 킥오프 프롬프트)을 이 스킬이 자동화하고, 받는 쪽 절반은 `session-init.sh`의 progress.md 자동 주입(state-schema §5)이 담당한다.

**[즉시 실행]** 아래 워크플로우를 바로 실행하세요.

## 옵션

| 호출 | 동작 |
|------|------|
| `/handoff` | 기본 — `.claude/state/progress.md`에 핸드오프 블록 append |
| `/handoff <진행문서경로>` | 지정 문서(예: `REDESIGN_PROGRESS.md`)의 ★CURRENT 섹션 교체 갱신 |

## Phase 1 — 맥락 추출 (대화에서)

현재 세션 대화에서 다음 5가지를 추출:

1. **완료** — 이번 세션에서 끝낸 것 (커밋 해시 포함)
2. **잔여** — 하다 만 것 + 정확한 다음 단계
3. **결정 대기 ⚠️** — 사용자 답변이 필요한 미결 질문
4. **환경/전제 변화** — 다음 세션이 알아야 할 환경 사실 (모델/버전/플래그 — 변한 것만)
5. **다음 첫 마디** — 새 세션에 붙여넣을 한 문장 명령

**추출 원칙**:
- 파일에서 다시 읽을 수 있는 것(코드 내용, 문서 본문)은 적지 않는다 — **포인터만** (`file:line`)
- **대화에만 존재하는 것을 우선 보존**: 결정과 그 이유, 시도했다 버린 접근, 사용자가 말로 준 제약
- 모호함이 있었으면 4섹션 패턴(설계결정/편차/트레이드오프/미결질문 ⚠️)으로 기록 — `docs/contracts/state-schema.md` §5

## Phase 2 — 진행 문서 갱신

- **기본**: `.claude/state/progress.md`에 state-schema §5 포맷으로 새 블록 append
- **진행 문서 지정 시**: 해당 문서의 ★CURRENT(또는 최상단 현재 섹션)를 교체 갱신. 이전 ★CURRENT 내용은 문서 하단 히스토리 섹션으로 이동 — **삭제 금지 (정보보존)**
- 미결 질문은 `⚠️` 마커 필수 (session-init이 강조 노출)

## Phase 3 — 킥오프 프롬프트 생성 + 클립보드 복사

아래 형식으로 생성:

```
<작업명> 이어가자. /clear 후 새 세션이야.
1. <진행 문서 경로> 의 ★CURRENT(최상단) 읽기 — <한 줄 상태 요약>.
2. 먼저 읽을 것: <파일 1-2개>
3. 잔여: <잔여 한 줄>. 보고 후 진행.
확인 받을 것: <결정 대기 항목, 없으면 생략>
가이드라인(불변): <프로젝트 불변 원칙 1줄>
```

Bash로 클립보드 복사 (시크릿/키 값 절대 포함 금지):

```bash
pbcopy <<'KICKOFF'
<생성한 프롬프트>
KICKOFF
```

## Phase 4 — 마무리 안내

사용자에게 한 줄 보고:

> progress.md 갱신 + 킥오프 프롬프트 클립보드 복사 완료. 이제 `/clear` 입력 후 ⌘V로 붙여넣으세요.

`/clear`는 사용자 전용 명령이라 모델이 대신 실행할 수 없다. 완전 자동화는 Forge Voice의 **⌘⇧K 매크로**로 가능 — `/clear` 입력 + 클립보드(킥오프) 붙여넣기 + 제출을 단축키 하나로 (`tools/forge-voice.lua`, `/voice setup` 시 설치). 음성 셋업을 안 했으면 위 수동 2단계.

## graceful skip

- `.claude/state/` 없음 → 생성 후 신규 작성
- `pbcopy` 없음(비 macOS) → 프롬프트를 코드블록으로 출력하고 수동 복사 안내
- 추출할 게 거의 없는 짧은 세션 → phase/next 두 줄만 기록 (4섹션 강제 금지)