finding-unknowns

name	finding-unknowns
description	장기작업의 지도(프롬프트·계획·컨텍스트)와 영토(코드베이스·현실·제약) 간극인 미지(unknowns)를 구현 전·중·후 반복 발견해 좁히는 오케스트레이션. Trigger: '장기작업 시작', '미지 찾기', 'unknowns', 'blindspot pass', 'map-territory', '방법론 적용', 새 대형 기능/프로젝트 킥오프, 낯선 도메인·API 진입, 가정 때문에 실패한 재시도. NOT for 인터뷰 단독 실행 (use grilling). NOT for 계획/코드 검증 루프 (use run-da). NOT for PR 생성/머지 절차 자체 (use create-pr / finish-pr — 이 스킬은 그 안의 게이트만 정의).

미지 찾기 (Finding Unknowns)

지도(map)는 에이전트에게 주어진 것 — 프롬프트·계획·스킬·컨텍스트. 영토(territory)는 작업이 실제 일어나는 곳 — 코드베이스·API·테스트·배포 환경·사용자 취향. 그 간극이 미지(unknowns)다. 장기작업의 품질은 미지를 얼마나 일찍, 싸게 발견하느냐에 병목이 걸린다 — 문제가 비싸지기 전의 발견 수단이 설명·프로토타입·인터뷰이고, 비싸진 후의 발견 수단이 재작업이다.

목표는 질문을 많이 하는 것이 아니라, 계획을 실질적으로 바꿀 소수의 답을 찾아내고 공유 이해를 기록하는 것이다.

미지 4분면

유형	의미	노출 수단
Known knowns	프롬프트/문서에 이미 있는 사실	재진술 + 출처 인용
Known unknowns	미해결임을 아는 결정	인터뷰 (grilling)
Unknown knowns	보면 알지만 미리 말 못 하는 취향/기준	대비되는 프로토타입·레퍼런스 (prototype)
Unknown unknowns	아무도 고려 못 한 제약/가능성	blindspot pass

적용 판단

적용: 다일(multi-day)·다세션·PR 규모 장기작업, 낯선 도메인/API/코드베이스 영역, 모호한 제품 방향, 이전 시도가 잘못된 가정으로 실패한 작업.

비적용: 사소·기계적 변경, 수용 기준이 이미 명확하고 도구 호출 한두 번으로 검증 가능한 작업. 비적용 판단 시에도 그 판단을 한 줄로 보고한다.

국면 1 — 구현 전

각 단계는 프로젝트 성격에 따라 스킵할 수 있으나, 스킵하면 사유 한 줄을 미지 원장에 기록한다. 무단 생략은 스킵이 아니라 unknown unknown의 방치다. 위임 대상 스킬(grilling/prototype)이 설치되지 않은 환경이면 이 문서에 적힌 해당 단계의 요지로 직접 수행한다.

1. 영토 정찰 — 관련 소스·테스트·설정·공식 문서를 사용자에게 묻기 전에 직접 읽는다(필요 시 정찰 서브에이전트 병렬). 코드/문서가 답할 수 있는 것을 사용자에게 묻지 않는다. 완료 기준: 정찰한 경로/문서 목록이 미지 원장에 적혀 있음.
2. Blindspot pass — unknown unknowns를 references/tactics.md의 출력 형식으로 나열한다: 리스크 순위 + 저렴한 해소 수단 + 결정 소유자(사용자/에이전트/문서/프로토타입). 완료 기준: 최고 리스크 미지마다 해소 수단이 지정됨.
3. 프로토타입 — unknown knowns가 많은 영역(시각 디자인, UX 흐름, "보면 아는" 기준)이면 prototype으로 의미 있게 대비되는 방향 여러 개를 만들어 반응을 받는다. 완료 기준: 사용자 반응이 명시적 기준 문장으로 원장에 언어화됨.
4. 인터뷰 — grilling으로 남은 known unknowns를 좁힌다. 모든 질문은 Material(답이 설계를 바꿈)·Grounded(증거 기반)·Answerable(선택지/기본값/레퍼런스로 답 가능) 3기준을 충족해야 한다 (상세와 블로킹 질문 템플릿: references/tactics.md). 아키텍처를 바꿀 질문 우선, 한 번에 하나 — blocking 질문 도구로 답을 기다리고, 답을 가정하고 진행하지 않는다. 저위험 미지는 질문하는 대신 기본값을 잠정 채택하고 가정 라벨을 붙여 원장·계획에 기록한다 — 게이트 A에서 계획과 함께 확인받으며, 확인 전에는 구현에 적용하지 않는다.
5. 레퍼런스 — 사용자가 원하는 바를 말로 다 못 하면 레퍼런스를 요청한다. 소스 코드가 최고의 레퍼런스다 — 다른 언어여도 가리키는 폴더를 읽고 의미를 재구현한다.
6. 구현 계획 — 변경 가능성 높은 결정(데이터 모델·타입 인터페이스·권한·사용자 대면 흐름)을 앞에, 기계적 작업을 뒤에 배치한다. 잔존 가정 목록과 "이 계획이 통제하지 못하는 것" 리스크 대장을 포함한다. run-da for_plan으로 검증한다.

게이트 A (빌드 전): 사용자가 공유 이해를 확인하기 전에 구현을 시작하지 않는다. 확인은 blocking 질문 도구로 받는다 — 침묵이나 정황을 동의로 간주하거나, 막히지 않았다는 이유로 가정하고 진행하지 않는다. 예외는 사용자가 "라벨된 가정과 함께 진행"을 명시 허용한 경우뿐이다.

국면 2 — 구현 중

• 워크트리 루트에 implementation-notes.md를 유지한다 (1행은 owner header, 최소 섹션: references/tactics.md). 아무리 계획해도 unknown unknowns는 구현 깊숙한 곳에서 나타난다 — 그것이 정상이며, 기록이 방법론의 산출물이다.
• 계획 이탈 시: 저위험·국소적이면 보수적 선택 → Deviations 기록 → 계속. 아키텍처·데이터 마이그레이션·보안·비용·사용자 대면 동작이 바뀌면 멈추고 질문한다.
• 영토(실측·공식 문서)가 계획과 모순되면 영토를 신뢰하고 계획을 갱신한다.
• 소실 방지 불변식: 이 파일은 커밋 대상이 아니다. 대신 create-pr이 PR 본문에 Decisions/Deviations를 흡수했음을 확인하기 전까지 삭제·이동하지 않는다. 임시 디렉토리로 옮기는 것도 이동이다. 흡수가 확인된 뒤에는 파일을 삭제한다 — 남겨두면 워크트리 정리(finish-pr)가 dirty 상태로 중단되고, 이후 발견되는 미지는 PR 본문 CIR을 직접 갱신하므로 파일이 더 필요하지 않다.

국면 3 — 구현 후

• 설명자료 — create-pr의 7섹션 본문이 설명자료다 (별도 산출물 불필요). 구현 노트의 Decisions/Deviations 흡수는 create-pr 절차가 수행한다.
• 퀴즈 — 머지 전 퀴즈 게이트는 finish-pr이 소유한다. 출제 규칙은 references/tactics.md. 이 국면에서 에이전트의 책임은 퀴즈를 출제할 수 있는 상태(노트가 PR 본문에 흡수됨)를 유지하는 것이다.
• 리뷰 루프도 영토다: PR 리뷰(review-pr-feedback)에서 실버그·설계 반전이 발견되면 그것도 미지 발견이다 — review-pr-feedback의 CIR 동기화 단계가 resolve 전에 PR 본문의 CIR/Deviations를 갱신한다. 방법론은 PR 초안에서 끝나지 않고 머지에서 끝난다.

하네스 매핑

방법론 단계	이 하네스에서	소유
blindspot pass	이 스킬이 직접 (정찰 + 4분면 정리)	finding-unknowns
브레인스토밍/프로토타입	prototype 스킬	prototype
인터뷰	grilling 스킬 + 질문 3기준	grilling / 이 스킬
구현 계획 검증	run-da for_plan	run-da
구현 노트	implementation-notes.md → PR 본문 흡수	이 스킬 / create-pr
설명자료	PR 7섹션 본문	create-pr
퀴즈 게이트	머지 전 통과 확인	finish-pr
리뷰 국면 기록	CIR/Deviations 갱신	review-pr-feedback + 이 스킬