ajitta/know-your-unknowns

Unknowns Loop — 강력한 모델과 함께 작업하기 위한 운영 루프

핵심 원칙: 강력한 모델의 병목은 모델 자체가 아니라, 사용자가 지도(계획)를 현실(영역)에 일치시키는 능력입니다. 그 격차가 바로 알려지지 않은 것입니다. 탐색 → 질문 → 계획 → 구현 → 이탈 로깅 → 검증 루프를 설계하는 것이 하나의 좋은 프롬프트보다 더 중요합니다.

출처: 11가지 "Know your unknowns" 예제; 루프 자체는 플러그인 확장입니다 — skills/loop/references/talk-source.md 참조.

출력: Artifact 도구 → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → 마크다운. 각 단계의 아티팩트는 자체 스킬의 반응 제어를 유지합니다. 루프 자체의 제어는 단계별 체크포인트이며, 이는 .unknowns/loop.json 트래커로 통합됩니다.

세부사항: skills/loop/references/output-routing.md

단계 (10단계 — 규모에 따라 축소)

1. 가치 및 완료 기준 정의

시작 전에 사용자와 확정: 목적 / 사용자 가치 / 완료 기준 / 절대 깨지면 안 되는 기존 동작 / 허용된 비용 및 변경 범위. 성공 기준 없이, 구현 양을 진전으로 착각하게 됩니다.

2. 블라인드 스팟 조사 → /unknowns:blindspot (또는 복사 설치의 경우 /blindspot)

구현 없이 조사만 수행합니다. 알려지지 않은 미지(unknown unknowns), 충돌 지점, 회귀 위험을 찾고 개선된 프롬프트를 생성합니다. 도메인 자체가 익숙하지 않은 경우(용어를 몰라 요청이 모호한 경우), /unknowns:teach-me를 함께 실행합니다.

3. 인터뷰 → /unknowns:interview

아키텍처를 변경하는 질문을 우선하며, 라운드당 최대 4개.

4. 솔루션 탐색 및 구체화 (필요 시)

• 무엇을 할지 미정 → /unknowns:brainstorm (솔루션 공간 지도)
• 어떻게 보여야 하는지를 말로 설명할 수 없음 → /unknowns:prototypes (분기적 목업)
• 모방할 예시가 있음 → /unknowns:reference (참조 분석)

5. 위험 가정 프로토타입 (필요 시)

전체 구현 전에, 가장 불확실한 기술적 가정만을 검증하는 최소 프로토타입을 구축합니다. 먼저 가정과 성공/실패 기준을 명시합니다.

6. 계획 → /unknowns:plan

실행 순서가 아닌 수정 가능성 확률에 따라 정렬된 조정 가능한 계획입니다. 사용자 입력이 필요한 결정(스키마, 인터페이스, UX 계약)이 상단에 위치합니다.

7. 구현 + 이탈 로그 → /unknowns:notes 규칙 적용

계획에 없는 모든 것을 로깅합니다. 아키텍처, 사용자에게 보이는 동작, 데이터 또는 보안에 영향을 미치는 결정에 대해서는 중단하고 질문합니다. 대화가 압축된 경우, 구현을 계속하기 전에 /unknowns:notes (및 단계 목록을 위한 이 스킬)을 다시 호출합니다.

8. 독립적 검증 → unknowns:independent-reviewer 에이전트

에이전트 도구(subagent_type: unknowns:independent-reviewer)를 사용하여 생성합니다. 절대 포크나 /subtask를 사용하지 마십시오 — 이들은 구현자의 컨텍스트를 상속하는데, 이것이 바로 이 단계에서 배제하고자 하는 것입니다. 에이전트에게 전달: 완료 기준(1단계), 승인된 계획(6단계), IMPLEMENTATION_NOTES.md 경로, diff 범위/영향받은 파일, 테스트 실행 방법. 구현자 자신의 요약은 절대 전달하지 마십시오.

9. 이해도 확인 및 인계 → /unknowns:quiz

사용자가 PR 또는 인계 시 이 작업을 설명할 수 있는지 확인합니다. 검토자나 이해관계자의 승인이 필요한 경우, /unknowns:buy-in 문서도 함께 생성합니다.

10. 가치 검토

코드 품질이 아닌 실제 가치로 판단합니다: 누구의 문제가 얼마나 줄었는지 / 어떤 부분이 얼마나 빨라졌는지 / 사용되지 않을 이유 / 지표 / 제거 조건. 구축은 더 쉽고, 가치 창출은 여전히 어렵습니다. 하나의 스코어카드 행을 캡처하여 마무리합니다 — 사용자에게 이것이 알지 못했던 것을 드러냈는지, 그리고 결정을 변경했는지 물어본 다음, 행을 .unknowns/scorecard.md에 추가합니다. 이 두 질문에 대해 사용자를 대신하여 답변하지 말고, 두 답변이 모두 '아니오'인 경우에도 행을 작성합니다. 세부사항: skills/loop/references/scorecard.md

축소 기준

• 소규모 수정(1~2개 파일, 명확한 스펙): 7단계 규칙(노트)만 적용 — 루프 불필요.
• 중간 규모 작업: 1(한 번 교환) → 2 → 3 → 6 → 7 → 9.
• 대규모 또는 낯선 작업: 모든 단계, 4와 5는 필요 시에만.
• 1단계는 모든 계층에서 실행됩니다. 계층을 모르겠으면 사용자에게 물어본 후 선택을 기록합니다.

루프 상태 (압축, /resume, 새 세션에서도 유지)

.unknowns/loop.json 유지 — {task, tier, stage, decisions[], artifacts[]} — 모든 단계 경계에서 다시 작성합니다. 각 단계를 하나의 AskUserQuestion 체크포인트(계속 / 건너뛰기 / 중단)로 마무리하고 답변을 거기에 기록합니다.

• 인수 status: 파일을 읽고 계층, 현재 단계, 남은 단계를 보고합니다.
• 인수 resume: 파일을 읽고 기록된 단계부터 계속합니다.
• 다른 인수 텍스트는 작업 설명입니다.
• 인수 없음: .unknowns/loop.json이 존재하면 재개하고, 그렇지 않으면 먼저 작업을 묻습니다.

운영 원칙 (요약)

1. 목적을 정의하라. 2. 구현 전에 블라인드 스팟을 찾아라. 3. 모델이 질문하게 하라. 4. 말 대신 참조와 프로토타입을 제공하라. 5. 계획을 수정 가능성 확률로 정렬하라. 6. 알려지지 않은 것과 계획 이탈을 로깅하라. 7. 테스트와 독립적 검토로 검증하라. 8. 사용자가 결과를 설명할 수 있는지 확인하라. 9. 결과물은 반응 가능한 형태로 제공하라. 10. 코드 양이 아닌 실제 가치를 측정하라.