feat(skills): finding-unknowns — 지도-영토 미지 방법론 오케스트레이션 스킬 - #1082
Conversation
Thariq 'Finding Your Unknowns' 방법론(미지 4분면, 구현 전·중·후 사이클)을 메모리 텍스트에서 전역 스킬로 승격. toss 세션(#1050 작업) 실측에서 확인된 3개 구멍에 강제장치를 배선: - 구현 노트 유실 → create-pr이 implementation-notes.md를 PR 본문 CIR로 흡수, 흡수 확인 전 삭제·이동 금지 불변식 - 퀴즈 게이트 미작동 → finish-pr 머지 절차에 퀴즈 게이트 단계 신설 (명시적 스킵 시 사유를 후속 코멘트에 기록) - 후반 리뷰 국면 이탈 → 리뷰 루프 발견도 미지로 정의, CIR/Deviations 갱신 grilling/prototype/run-da/create-pr/finish-pr 조합·AskUserQuestion 결합이라 Codex 비노출(intentionallyNotExposed) + skill-neutral lint 제외로 등록. Claude-Session: https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthrough
Changesfinding-unknowns 통합
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant Claude
participant ImplementationNotes
participant CreatePR
participant ReviewPRFeedback
participant FinishPR
Claude->>ImplementationNotes: Decisions와 Deviations 기록
CreatePR->>ImplementationNotes: CIR 흡수 및 durable marker 추가
ReviewPRFeedback->>CreatePR: 유효 피드백 기반 CIR 동기화
FinishPR->>Claude: PR 본문 기반 퀴즈 출제
FinishPR->>FinishPR: headRefOid 재조회
FinishPR->>CreatePR: 고정 head SHA로 squash merge
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@modules/shared/programs/claude/files/skills/create-pr/SKILL.md`:
- Line 58: After CIR absorption, explicitly remove worktree
implementation-notes.md only after confirming PR body creation or update
succeeded; add this cleanup step to both the new-PR and PR-update procedures,
while retaining the prohibition against deleting or moving it before absorption
is reported complete.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4709aa35-8d6d-42c9-8a3d-1aad7692fb2a
📒 Files selected for processing (7)
modules/shared/programs/claude/default.nixmodules/shared/programs/claude/files/skills/create-pr/SKILL.mdmodules/shared/programs/claude/files/skills/finding-unknowns/SKILL.mdmodules/shared/programs/claude/files/skills/finding-unknowns/references/tactics.mdmodules/shared/programs/claude/files/skills/finish-pr/SKILL.mdmodules/shared/programs/codex/default.nixscripts/ai/verify-ai-compat.sh
CodeRabbit 지적 반영: 흡수 전 삭제·이동 금지만 있고 흡수 후 동작이 없어, 노트 파일이 남으면 wt cleanup(_wt_is_dirty의 git status --porcelain이 untracked 포함)이 dirty로 중단됨을 실측 확인. finding-unknowns 불변식(SoT)과 create-pr 새 PR/update 절차 양쪽에 '성공 확인 후 삭제, 실패 시 보존' 추가. Claude-Session: https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH
greenheadHQ
left a comment
greenheadHQ
left a comment
There was a problem hiding this comment.
전체 diff를 고정 base/head 기준으로 검토했습니다. 방법론의 핵심 강제장치가 세션·리뷰·런타임·실제 merge 대상까지 이어지는지 중심으로 확인했고, 재현 가능한 6건을 인라인에 남깁니다.
- durable marker: create-pr 흡수 계약이 PR 본문에 hidden marker를 기록, finish-pr 퀴즈 게이트의 1차 판별 신호로 사용 (별도 세션에서 게이트 증발 방지) - provenance guard: 노트 1행 owner header + untracked 확인 + 본문 반영 확인 3중 조건 충족 시에만 흡수·삭제 (전역 스킬의 동명 파일 오삭제 방지) - 흡수 계약 SSOT: 새 PR 경로 정의를 정본으로 update 경로가 참조, '새로 발견된 미지' 섹션 유실 해소 - 리뷰 국면 실배선: review-pr-feedback Step 5.5 신설 — marker PR에서 유효 피드백 반영 시 resolve 전 CIR/Deviations 증분 동기화 (stale 퀴즈 방지) - 질문 도구 런타임 매핑: 퀴즈 출제를 run-da runtime-mapping SoT에 연결, 한 문항씩 순차 출제 고정 (Codex plain-text 퇴행 방지) - merge 재고정: 퀴즈 통과 직후 headRefOid/body 재조회 + 변경 시 퀴즈 재시작, merge는 --match-head-commit으로 SHA 고정 (TOCTOU race 봉쇄) Claude-Session: https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@modules/shared/programs/claude/files/skills/create-pr/SKILL.md`:
- Around line 68-69: 구현 노트 삭제 전 검증 조건을 강화하세요. 3단계의 implementation-notes.md 흡수 및
새 PR/update 경로 모두에서 Decisions, Deviations, 새로 발견된 미지의 세 섹션이 각각 PR 본문에 반영되었고
durable marker도 포함되었는지 확인하도록 명시하세요. 세 섹션 중 하나라도 누락되거나 검증에 실패하면 파일을 삭제하지 말고 중단하도록
관련 절차를 수정하세요.
- Around line 58-68: PR 본문을 셸 인자로 전달하지 않도록 6단계의 gh pr create 호출을 수정하세요. 7섹션 템플릿과
implementation-notes.md 흡수 내용으로 본문 파일을 생성한 뒤 gh pr create의 --body-file을 사용하거나
stdin 기반 전달 방식으로 통일하고, 기존 --body "<본문>" 경로를 제거하세요.
In `@modules/shared/programs/claude/files/skills/review-pr-feedback/SKILL.md`:
- Around line 153-159: Step 5.5의 skip 조건을 코드 변경 여부가 아니라 이번 run에서 새 CIR,
Deviation, unknown 또는 설계 결정이 발견되었는지로 판단하도록 수정하세요. 특히 DESIGN_TRADEOFF,
TECHNICAL_DISAGREEMENT, SCOPE_DEFERRAL로 기각한 피드백에서도 생성된 기록을 수집해 PR 본문의
CIR/Deviations에 증분 동기화하고, 해당 기록이 전혀 없을 때만 단계를 건너뛰도록 안내를 갱신하세요.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 18278a52-f8dd-4599-9010-9d795dae5365
📒 Files selected for processing (5)
modules/shared/programs/claude/files/skills/create-pr/SKILL.mdmodules/shared/programs/claude/files/skills/finding-unknowns/SKILL.mdmodules/shared/programs/claude/files/skills/finding-unknowns/references/tactics.mdmodules/shared/programs/claude/files/skills/finish-pr/SKILL.mdmodules/shared/programs/claude/files/skills/review-pr-feedback/SKILL.md
✅ Files skipped from review due to trivial changes (2)
- modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.md
- modules/shared/programs/claude/files/skills/finding-unknowns/references/tactics.md
🚧 Files skipped from review as they are similar to previous changes (1)
- modules/shared/programs/claude/files/skills/finish-pr/SKILL.md
- create-pr: PR 생성/업데이트 본문을 --body-file로 통일 (multiline 본문의 argv/프로세스 목록 노출 방지, review-pr-feedback 전달 규칙과 정합) - create-pr: 노트 삭제 조건 ③을 '세 섹션 각각 + marker 모두 반영'으로 명시 (일부 섹션만 반영된 상태로 통과 금지) - review-pr-feedback Step 5.5: skip 기준을 코드 무변경에서 '새 CIR 기록 전무'로 교체 — 기각(DESIGN_TRADEOFF 등)이 남긴 설계 결정·이관 미지도 동기화 대상 Claude-Session: https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH
greenheadHQ
left a comment
greenheadHQ
left a comment
There was a problem hiding this comment.
최신 head에서 전체 diff를 다시 검토했습니다. 이전 9개 지적은 해결된 것으로 확인했습니다. 새로 남은 7건을 인라인에 적었습니다. 추가로 live PR 본문을 조회한 결과 <!-- methodology: finding-unknowns --> marker가 0개이므로, 현재 PR 자체는 backfill 전까지 finish-pr의 1차 퀴즈 신호로 식별되지 않습니다.
| 1. 이 PR이 finding-unknowns 방법론 적용 작업인지 판별한다. 1차 신호는 PR 본문의 durable marker `<!-- methodology: finding-unknowns -->`다 (기록 주체·정본: create-pr 흡수 계약 — 별도 세션에서도 남는 유일한 신호). 보조 신호는 세션·메모리 컨텍스트의 방법론 적용 선언, 워크트리에 남은 `implementation-notes.md`이며, 보조 신호만으로 판별할 때는 일반 PR 오탐에 주의한다. | ||
| 2. 해당되면 머지 전에 변경의 동작 이해를 확인하는 퀴즈를 질문 도구로 출제한다 (런타임별 질문 도구 binding: [run-da의 런타임 도구 매핑](../run-da/references/runtime-mapping.md#런타임-도구-매핑) — blocking tool call 필수, plain-text 질문으로 퇴행 금지). 출제 규칙의 SoT는 finding-unknowns 스킬의 `references/tactics.md` — 요지: 변경 규모에 따라 총 3~5문항을 한 문항씩 답을 기다려 순차 출제하고, 모든 문항은 PR 본문만 읽어도 답할 수 있어야 하며, 오답이면 설명 후 그 주제로 재출제한다. | ||
| 3. 전 문항 정답이 통과다. 통과 전에는 squash merge를 진행하지 않는다. | ||
| 4. 퀴즈 통과 직후 merge 대상을 다시 고정한다: `gh pr view --json headRefOid,body,statusCheckRollup,reviewDecision,mergeStateStatus`를 재조회하고, 퀴즈 시작 시점 대비 head 또는 본문이 바뀌었으면 바뀐 내용 기준으로 퀴즈를 다시 시작한다 (이전 head에 대한 통과로 새 head를 머지하지 않는다). 재확정한 `headRefOid`를 3단계 merge에 전달한다. |
There was a problem hiding this comment.
[P1] 재조회한 CI·review·merge 상태를 gate에 다시 적용해 주세요
여기서는 statusCheckRollup, reviewDecision, mergeStateStatus까지 다시 가져오지만 실제 분기는 head/body 변경 여부뿐입니다. 퀴즈 도중 같은 head에서 check rerun이 실패하거나 승인이 철회되거나 base 갱신으로 conflict가 생겨도 다음 merge로 진행합니다. 현재 main은 branch protection API가 404이고 ruleset도 비어 있어 서버가 이를 대신 막지 않습니다. 재조회 결과에 Step 1의 gate를 다시 적용해 pending/실패 check, conflict, required review 미승인이면 STOP하고, 모두 통과한 뒤에만 SHA를 merge 단계로 넘겨 주세요.
|
|
||
| ### 3. squash merge | ||
|
|
||
| 1. 직전에 확인한 head commit SHA를 고정해 `gh pr merge <pr> --squash --match-head-commit "$HEAD_OID"`로 squash merge한다 (확인~merge 사이에 새 push가 끼어들면 merge가 실패하도록 — 퀴즈 게이트를 거친 PR은 2단계 4항에서 재확정한 SHA를 사용한다). |
There was a problem hiding this comment.
[P1] 모든 merge 경로에서 head SHA를 공통 preflight로 정의해 주세요
이 명령은 모든 PR에서 $HEAD_OID를 요구하지만, headRefOid를 얻는 절차는 방법론 PR이 퀴즈를 통과한 line 38뿐입니다. 일반 PR, marker 미탐지, 명시적 퀴즈 skip 경로는 line 38을 건너뛰고 Step 1 쿼리에도 headRefOid가 없어 값이 없습니다. 또한 이 저장소의 runtime 계약상 shell 변수는 별도 tool call 사이에 유지되지 않습니다. 모든 open PR 경로가 merge 직전 공통 preflight에서 headRefOid를 가져오게 하고, 다음 call에는 실제 SHA literal을 전달하거나 조회와 merge를 같은 shell call로 묶어 주세요.
|
|
||
| ### Step 5.5: 방법론 PR의 CIR 동기화 (finding-unknowns) | ||
|
|
||
| PR 본문에 durable marker `<!-- methodology: finding-unknowns -->`가 있고(기록 주체·정본: create-pr 흡수 계약) 이번 run이 새 CIR 기록을 만들었다면, Step 6의 답글·resolve 전에 PR 본문의 CIR/Deviations를 동기화한다 — create-pr의 `update` 절차를 수행하는 handoff이며, 본문 전면 재작성이 아니라 CIR/Deviations 증분 갱신이다. "새 CIR 기록"은 코드에 반영한 실버그·설계 반전만이 아니라, `DESIGN_TRADEOFF`/`TECHNICAL_DISAGREEMENT`/`SCOPE_DEFERRAL` 기각이 남긴 설계 결정과 이관된 미지(분리 이슈 #N)도 포함한다 — 코드 무변경이 skip 기준이 아니다. 이 동기화를 건너뛰면 이후 finish-pr 퀴즈가 stale한 본문을 기준으로 출제된다. |
There was a problem hiding this comment.
[P1] review 대상 PR identity를 create-pr update까지 고정해 주세요
이 스킬의 입력은 현재 PR뿐 아니라 PR 번호/URL도 허용하지만, handoff 대상인 create-pr update는 인자로 update만 받고 gh pr view로 현재 브랜치 PR을 찾습니다. 예를 들어 main에서 다른 브랜치의 PR 번호를 리뷰하면 Step 5.5가 대상 PR이 아니라 현재 브랜치 PR을 수정하거나 실패해 원래 CIR을 stale하게 남길 수 있습니다. Step 1에서 확정한 repo+PR number/URL을 handoff schema에 포함하고 gh pr view/edit <target> 모두 같은 identity를 쓰게 하세요. 동기화 실패 시에는 답글·resolve 전에 STOP해야 합니다.
| 5. 7섹션 템플릿 작성: [references/pr-template.md](references/pr-template.md)의 템플릿에 따라 전체 PR 본문을 작성한다. | ||
| 6. PR 생성: `gh pr create --title "<제목>" --body "<본문>"`으로 PR을 생성한다. 제목은 70자 미만, conventional commit 형식을 따른다. | ||
| 6. PR 생성: 본문을 임시 파일로 작성한 뒤 `gh pr create --title "<제목>" --body-file <파일>`로 PR을 생성한다 — 본문을 shell 인자로 싣지 않는다 (multiline 본문의 프로세스 목록/로그 노출 방지, review-pr-feedback의 파일/stdin 전달 규칙과 동일). 제목은 70자 미만, conventional commit 형식을 따른다. | ||
| 7. 구현 노트 정리: 3단계에서 `implementation-notes.md`를 흡수한 경우, 다음 세 조건을 모두 확인한 뒤에만 그 파일을 삭제한다 (남겨두면 finish-pr의 워크트리 정리가 dirty로 중단됨) — ① 1행 owner header 일치, ② `git ls-files --error-unmatch -- implementation-notes.md` 실패(untracked; tracked면 Git 밖 삭제 금지), ③ 생성된 PR 본문에 Decisions·Deviations·새로 발견된 미지 세 섹션 각각과 durable marker가 모두 반영되었는지 확인 (일부 섹션만 반영된 상태로 통과 금지). 하나라도 어긋나거나 PR 생성이 실패하면 파일을 보존하고 중단한다. |
There was a problem hiding this comment.
[P1] 삭제 검증을 실제로 흡수한 노트 스냅샷에 묶어 주세요
현재 세 조건은 파일의 provenance와 PR 본문 구조만 확인합니다. 에이전트 A가 N0을 읽어 본문을 만든 뒤, 삭제 전에 다른 세션/사용자가 새 미지를 추가해 N1이 되어도 owner header·untracked·세 섹션+marker 조건은 그대로 통과해 최신 N1을 삭제할 수 있습니다. 흡수 시작 시 노트 content hash/generation을 고정하고 삭제 직전에 다시 비교하세요. drift가 있으면 삭제하지 말고 최신 내용으로 흡수부터 재시작해야 이 PR의 핵심인 노트 유실 방지가 성립합니다.
| 2. 누락 섹션 탐지: 7섹션 중 빠진 섹션을 식별한다. | ||
| 3. 부실 섹션 강화: 있지만 내용이 부실한 섹션(예: Summary만 있고 CIR 없음)을 보강한다. 커밋 히스토리, 코드 변경, 대화 컨텍스트에서 추가 정보를 수집한다. | ||
| 4. 업데이트 적용: `gh pr edit <number> --body "<새 본문>"`으로 PR 본문을 업데이트한다. | ||
| 3. 부실 섹션 강화: 있지만 내용이 부실한 섹션(예: Summary만 있고 CIR 없음)을 보강한다. 커밋 히스토리, 코드 변경, 대화 컨텍스트에서 추가 정보를 수집한다. 워크트리에 `implementation-notes.md`가 있으면 새 PR 생성 절차의 흡수 계약을 그대로 적용한다 (provenance 확인, 세 섹션 전부, durable marker — marker가 본문에 없으면 이때 기록). |
There was a problem hiding this comment.
[P1] marker lifecycle을 노트 존재와 분리해 주세요
update 경로가 marker를 추가하는 조건은 여전히 implementation-notes.md가 남아 있을 때뿐인데, 정상 create 흐름은 line 68에서 그 노트를 삭제합니다. 이후 full-body update가 marker를 누락하거나 기존 방법론 PR을 backfill해야 해도 복구 경로가 없습니다. 실제 현재 PR #1082 본문도 방법론 적용을 명시하지만 marker count는 0입니다. update 시작 시 기존 marker를 노트와 무관하게 보존하고 post-write로 재검증하며, 명시적으로 확인된 기존 방법론 PR에는 노트 없이도 안전하게 backfill할 절차를 정의해 주세요.
|
|
||
| 1. `gh pr merge <pr> --squash`로 squash merge한다. | ||
| 1. 이 PR이 finding-unknowns 방법론 적용 작업인지 판별한다. 1차 신호는 PR 본문의 durable marker `<!-- methodology: finding-unknowns -->`다 (기록 주체·정본: create-pr 흡수 계약 — 별도 세션에서도 남는 유일한 신호). 보조 신호는 세션·메모리 컨텍스트의 방법론 적용 선언, 워크트리에 남은 `implementation-notes.md`이며, 보조 신호만으로 판별할 때는 일반 PR 오탐에 주의한다. | ||
| 2. 해당되면 머지 전에 변경의 동작 이해를 확인하는 퀴즈를 질문 도구로 출제한다 (런타임별 질문 도구 binding: [run-da의 런타임 도구 매핑](../run-da/references/runtime-mapping.md#런타임-도구-매핑) — blocking tool call 필수, plain-text 질문으로 퇴행 금지). 출제 규칙의 SoT는 finding-unknowns 스킬의 `references/tactics.md` — 요지: 변경 규모에 따라 총 3~5문항을 한 문항씩 답을 기다려 순차 출제하고, 모든 문항은 PR 본문만 읽어도 답할 수 있어야 하며, 오답이면 설명 후 그 주제로 재출제한다. |
There was a problem hiding this comment.
[P2] 질문 도구가 없는 headless 경로는 명시적으로 STOP해 주세요
연결한 runtime mapping은 headless 세션의 질문 도구를 미지원으로 표시하지만, 여기에는 안전한 전이 규칙이 없습니다. 퀴즈는 전 문항 통과 또는 사용자의 명시적 skip만 허용하므로 run-da 전용 자동 전이를 재사용할 수도 없습니다. 지금 상태에서는 headless finish-pr가 plain-text로 퇴행하거나 퀴즈 없이 계속하거나 도중 실패할 여지가 있습니다. 질문 도구 미지원이면 GitHub write 전에 STOP하고 interactive Claude/Codex 세션으로 handoff하도록 별도 분기를 추가해 주세요.
| - 워크트리 루트에 `implementation-notes.md`를 유지한다 (1행은 owner header, 최소 섹션: [references/tactics.md](references/tactics.md)). 아무리 계획해도 unknown unknowns는 구현 깊숙한 곳에서 나타난다 — 그것이 정상이며, 기록이 방법론의 산출물이다. | ||
| - 계획 이탈 시: 저위험·국소적이면 보수적 선택 → Deviations 기록 → 계속. 아키텍처·데이터 마이그레이션·보안·비용·사용자 대면 동작이 바뀌면 멈추고 질문한다. | ||
| - 영토(실측·공식 문서)가 계획과 모순되면 영토를 신뢰하고 계획을 갱신한다. | ||
| - 소실 방지 불변식: 이 파일은 커밋 대상이 아니다. 대신 `create-pr`이 PR 본문에 Decisions/Deviations를 흡수했음을 확인하기 전까지 삭제·이동하지 않는다. 임시 디렉토리로 옮기는 것도 이동이다. 흡수가 확인된 뒤에는 파일을 삭제한다 — 남겨두면 워크트리 정리(`finish-pr`)가 dirty 상태로 중단되고, 이후 발견되는 미지는 PR 본문 CIR을 직접 갱신하므로 파일이 더 필요하지 않다. |
There was a problem hiding this comment.
[P2] 노트 수명 조건은 create-pr 흡수 계약만 참조해 주세요
이 문장과 line 55는 Decisions/Deviations가 흡수되면 완료된 것처럼 요약하지만, 정본인 create-pr 계약은 새로 발견된 미지까지 세 섹션 모두와 marker 반영을 요구합니다. 오케스트레이터의 더 이른 문구를 따르면 미지 섹션이 남은 상태에서도 삭제 가능하다고 해석될 수 있고, 두 정의는 다시 drift할 수 있습니다. 섹션 목록을 복제하지 말고 “create-pr 흡수 계약의 완료 조건을 충족하기 전까지”로 단일 정본을 직접 참조해 주세요.
greenheadHQ
left a comment
greenheadHQ
left a comment
There was a problem hiding this comment.
추가로 원래 요구사항인 Claude Code·Direct Codex 양쪽 호환을 기준으로 노출 정책과 사용자 상호작용 경로를 검증했습니다. 현재 Codex discovery를 의도적으로 차단하는 P1 1건과, 노출 후에도 인터뷰 binding이 빠지는 P2 1건을 인라인에 남깁니다.
| "codex-fan-out" | ||
| # finding-unknowns: Claude 하네스 전용 오케스트레이터 — grilling/prototype/run-da/create-pr/finish-pr | ||
| # 조합과 AskUserQuestion 인터뷰·퀴즈에 결합되어 있어 Codex 단독 세션에선 의미가 없다. | ||
| "finding-unknowns" |
There was a problem hiding this comment.
[P1] finding-unknowns를 Codex에도 실제로 노출해 주세요
원래 요구사항은 Claude Code와 Direct Codex 양쪽 호환인데, 이 항목은 finding-unknowns를 intentionallyNotExposed로 분류해 codexSkillEntries가 ~/.codex/skills/finding-unknowns를 만들지 않게 합니다. 현재 Codex 설치와 이 세션의 skill catalog에서도 실제로 누락되어 발견·발동할 수 없고, verify-ai-compat.sh의 SHARED_EXPOSURE_EXCLUDE와 SKILL_NEUTRAL_LINT_EXCLUDE도 그 비노출을 성공 조건으로 고정합니다. 반면 이 PR의 tactics.md는 이미 중립적인 “질문 도구”와 Claude=AskUserQuestion/Codex=request_user_input binding을 사용하며, grilling·prototype과 run-da·create-pr·finish-pr·review-pr-feedback도 Codex에서 발견됩니다. 이 스킬을 exposedCodexSkills 및 verifier의 EXPECTED_EXPOSED로 옮기고 두 exclusion에서 제거한 뒤, PR Human Test Plan에 Claude/Codex 각각의 discovery·trigger·질문 게이트 실측을 추가해 주세요. 남는 런타임 차이는 비노출로 우회하지 말고 runtime mapping에서 끝까지 binding해야 합니다.
| 1. 영토 정찰 — 관련 소스·테스트·설정·공식 문서를 사용자에게 묻기 전에 직접 읽는다(필요 시 정찰 서브에이전트 병렬). 코드/문서가 답할 수 있는 것을 사용자에게 묻지 않는다. 완료 기준: 정찰한 경로/문서 목록이 미지 원장에 적혀 있음. | ||
| 2. Blindspot pass — unknown unknowns를 [references/tactics.md](references/tactics.md)의 출력 형식으로 나열한다: 리스크 순위 + 저렴한 해소 수단 + 결정 소유자(사용자/에이전트/문서/프로토타입). 완료 기준: 최고 리스크 미지마다 해소 수단이 지정됨. | ||
| 3. 프로토타입 — unknown knowns가 많은 영역(시각 디자인, UX 흐름, "보면 아는" 기준)이면 `prototype`으로 의미 있게 대비되는 방향 여러 개를 만들어 반응을 받는다. 완료 기준: 사용자 반응이 명시적 기준 문장으로 원장에 언어화됨. | ||
| 4. 인터뷰 — `grilling`으로 남은 known unknowns를 좁힌다. 모든 질문은 Material(답이 설계를 바꿈)·Grounded(증거 기반)·Answerable(선택지/기본값/레퍼런스로 답 가능) 3기준을 충족해야 한다 (상세와 블로킹 질문 템플릿: [references/tactics.md](references/tactics.md)). 아키텍처를 바꿀 질문 우선, 한 번에 하나. 저위험 미지는 질문하는 대신 기본값을 선택하고 가정 라벨을 붙인다. |
There was a problem hiding this comment.
[P2] 구현 전 인터뷰도 런타임별 blocking 질문 도구에 bind해 주세요
퀴즈 경로는 tactics.md:95에서 Claude=AskUserQuestion, Codex=request_user_input으로 올바르게 매핑했지만, 이 핵심 인터뷰 경로는 grilling에만 위임합니다. 현재 grilling 계약은 한 문항씩 기다리라고만 할 뿐 request_user_input을 명시하지 않고, 이 저장소의 AGENTS.override.md는 default mode 모델이 자동 호출하지 않으므로 인터뷰·사용자 확인 단계에서 plain-text 대신 request_user_input을 명시하라고 요구합니다. 따라서 스킬을 노출해도 Direct Codex에서는 인터뷰와 게이트 A 확인이 plain-text로 퇴행할 수 있습니다. material 질문과 공유 이해 확인에도 동일 runtime mapping을 연결해 blocking 도구 호출을 필수화하고, 양 런타임에서 한 문항씩 실제로 정지·재개되는 smoke test를 Human Test Plan에 추가해 주세요.
머지 후 검증 결과
후속: Codex 노출 전환(동등 지휘자 + 행동 지시 중립화)은 grilling 세션 합의에 따라 별도 PR로 진행 예정. |
* feat(skills): finding-unknowns를 Codex에도 노출 — 동등 지휘자 + 행동 계약 중립화 grilling 세션 합의 (PR #1082 후속): - 노출 전환: intentionallyNotExposed → exposedCodexSkills (verify-ai-compat EXPECTED_EXPOSED 이동, SKILL_NEUTRAL_LINT_EXCLUDE 제거) - 근거 실측: Codex user 스코프는 ~/.agents/skills — grilling/prototype이 맥북·miniPC 양쪽에서 이미 발견됨 (codex exec 스킬 목록 probe로 확인). 기존 ~/.codex/skills 노출 경로도 인식 확인 - 중립화: 도구명 리터럴(AskUserQuestion/request_user_input)과 runtime-mapping 링크를 제거하고 행동 계약만 유지 — 'blocking 질문 도구로 한 문항씩 답을 기다리고, plain-text로 묻고 지나가거나 가정하고 진행 금지' - Codex 성향 보정: 게이트 A·인터뷰에 명시 지시 (default mode의 make-assumptions-and-only-stop-if-blocked 정책 대응, run-da 선례) - 이식성: grilling/prototype 미설치 환경은 문서 요지로 직접 수행 폴백 Claude-Session: https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH * docs(skills): 저위험 기본값 규칙과 게이트 A 정합 — 잠정 채택·기록, 확인 전 적용 금지 CodeRabbit 지적 반영: '기본값을 선택하고'가 강화된 게이트 A(가정 직진 금지)와 표면 충돌해 오독 여지 — 기본값은 원장·계획에 잠정 기록되고 게이트 A에서 계획과 함께 확인받는다는 우선순위를 문구로 명시. Claude-Session: https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH
1 participant
Summary
finding-unknowns로 승격한다.기존 문제/배경
방법론은 2026-07-08 메모리(
map-territory-unknowns)로 채택되어 토스 OpenAPI 인프라 장기작업에 적용됐다. 해당 세션 로그(8.8MB, 4,014라인) 전수 분석 결과, 구현 전 단계(정찰 → blindspot pass → 인터뷰 → 계획 v7 + DA 검증)는 충실히 작동했으나 이후가 무너졌다:원인은 방법론이 강제장치 없는 메모리 산문으로만 존재했기 때문이다. 좋은 단계별 도구(grilling·prototype·run-da·create-pr·finish-pr)는 이미 있으므로, 빠진 것은 코스 순서와 게이트를 소유하는 오케스트레이션 스킬이다.
CIR (Change Intent Record)
grilling계열 + Thariq 아티클의 통합 스킬, MIT) 조사 후, 외부 스킬 설치 대신 이 하네스 전용 오케스트레이션 스킬을 자체 제작. 사용자 인터뷰로 3개 설계 결정 확정: ① 풀코스 오케스트레이션(구멍 3개만 보강하는 경량안 기각), ② 구현 노트는 PR 본문 CIR로 흡수(레포 커밋안 기각), ③ 퀴즈는 finish-pr 머지 전 게이트(권장-only안 기각).trade-off: finish-pr 절차에 게이트 단계가 하나 늘어 방법론 적용 작업의 머지가 한 턴 느려진다. 대신 "통과 후에만 머지"가 관문(머지)에 물리적으로 결합되어 증발이 불가능해진다. 명시적 스킵(사유 기록)을 열어 급한 머지의 탈출구는 유지한다.
ADR
구현 상세
modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.mdmodules/shared/programs/claude/files/skills/finding-unknowns/references/tactics.mdmodules/shared/programs/claude/files/skills/create-pr/SKILL.mdmodules/shared/programs/claude/files/skills/finish-pr/SKILL.mdmodules/shared/programs/claude/default.nix~/.claude/skills/finding-unknownsmkOutOfStoreSymlink 배선modules/shared/programs/codex/default.nixintentionallyNotExposed에 등록 (Claude 하네스 전용 오케스트레이터)scripts/ai/verify-ai-compat.shSHARED_EXPOSURE_EXCLUDE+SKILL_NEUTRAL_LINT_EXCLUDE등록modules/shared/programs/claude/files/skills/review-pr-feedback/SKILL.md핵심 설계 (소실 방지 불변식)
참고 레퍼런스
grilling/domain-modeling(이 스킬이 인터뷰 단계를 위임하는 대상)Human Test Plan
정상 동작 검증
nrs후ls -la ~/.claude/skills/finding-unknowns를 실행한다.modules/shared/programs/claude/default.nix배선 항목과 home-manager 재활성화 여부 확인.~/.claude/skills/finding-unknowns/SKILL.mdfrontmatter)../scripts/ai/verify-ai-compat.sh를 실행한다.~/.codex/skills/finding-unknowns심링크가 존재하면 안 됨 — codex default.nix의 intentionallyNotExposed 등록 확인.게이트 검증
implementation-notes.md를 남긴 상태에서 PR 생성을 요청한다.Regression
https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH
Summary by CodeRabbit
finding-unknowns스킬을 제공해 구현 전·중·후 unknowns를 반복적으로 발굴하고 축소하는 절차/템플릿을 사용할 수 있습니다.create-pr/update에서implementation-notes.md흡수 계약과 PR 본문 신호(듀러블 마커) 기반의 CIR·Deviations 동기화가 더 명확해졌습니다(흡수 완료 전 보존 조건 포함).finish-pr에 방법론 적용 PR 전용 퀴즈 게이트를 추가하고(통과 전 머지 보류, 재시작/스킵 조건 포함) 단계 구성을 재정리했습니다.