finding-unknowns

Execution contract

입력은 사용자 요청과 작업 리포다. 메인 에이전트가 필요한 사실을 조사하고 미정인 도메인 결정을 사용자와 확정한다. 요청이 없으면 작업 목표를 묻는다. 출력은 확정된 서비스 동작과 검증 기준이다. 설계 문서를 승인받았으면 경로를 groundwork:executing-design에 넘긴다. 요청만으로 동작과 범위가 명확하면 별도 인터뷰·설계 승인 없이 실행한다. 아래 산출물 경로는 작업 리포 루트 기준이며, 이 스킬의 링크는 스킬 디렉터리 기준이다.

Decision authority

도메인 결정은 서비스가 무엇을 하는지 정한다. 기능의 의미, 업무 규칙, 역할과 권한, 실패·취소·재시도·재개 때 사용자가 보는 결과가 해당한다. 요청에 없고 선택별 사용자 결과가 다른 정책은 사용자에게 묻는다. 기존 코드·문서·참조 구현은 현재 상태의 증거이지 새 기능의 목표 정책이 아니다. 합의된 정책도 대화 중 목표·영향·제약이 새로 드러나면 재검토한다. 기존 결정과 무엇이 달라졌고 왜 다시 판단해야 하는지 설명한다. 파일 구조·모듈·저장소·인프라·알고리즘 등 기술 선택은 에이전트가 조사하고 결정한다. 선택이 도메인 결과도 바꾸면 사용자에게는 그 결과의 차이를 묻는다. 마지막 수정 우선의 승자 기준도 누구의 내용이 남는지를 바꾸는 도메인 결정이다.

Investigate as needed

요청과 관련된 현재 흐름을 읽고, 변경이 영향을 주는 계약과 실패 경로를 확인한다. 외부 사양은 공식 자료로 확인하고, 확인하지 못한 사실은 가정이라고 밝힌다. 기존 정책을 새 상황에 적용했을 때 사용자가 무엇을 겪는지 살펴본다. 정상 흐름뿐 아니라 이번 기능에 적용되는 실패·취소·재시도·권한·다른 참여자에 대한 영향을 본다. 조사는 발견한 위험에 맞게 선택한다. 조사원 수나 기법 종류를 채우기 위해 디스패치하지 않는다.

• 숨은 결합이나 영향 범위가 불명확하면 blindspot-prompt.md로 조사할 수 있다.
• 기존 해법과 비교해야 하면 reference-prompt.md를 쓸 수 있다.
• 문서만으로 중요한 가정을 확인할 수 없으면 spike-prompt.md로 버릴 코드에서 검증할 수 있다.
• 취향이나 상호작용을 말로 고르기 어려우면 실물을 병치한다. 프로토타입은 목표 동작을 독단으로 확정하는 수단이 아니다.

Explain the decision before asking

질문 하나만 읽어도 사용자가 판단할 수 있도록 아래 내용을 함께 설명한다. 설명 분량은 이해에 필요한 만큼 쓴다.

1. 경위와 쟁점: 요청과 현재 동작에서 어떤 갈림길을 발견했고 왜 지금 정해야 하는가. 확인한 사실과 아직 미정인 정책을 구분한다.
2. 선택별 동작: 각 선택에서 누구에게 무엇이 보이고 무엇을 할 수 있는가. 기술 용어 대신 실제 시나리오로 설명한다.
3. 결과와 대가: 다른 사용자, 데이터, 기존 업무에 미치는 영향과 각 선택에서 얻거나 감수하는 것을 설명한다. 알 수 없는 영향은 단정하지 않는다. 선택지가 정하지 않은 복구 여부·권한·우선순위나 확인하지 않은 구현 시간을 사실처럼 덧붙이지 않는다. 결정에 필요하면 미정인 정책으로 설명해 묻는다.
4. 추천 근거: 추천한다면 사용자가 밝힌 목표와 연결한다. 목표가 없으면 조건부 추천임을 밝히거나 추천을 생략한다. 구현이 편하다는 이유로 서비스 정책을 기본값으로 정하지 않는다.
5. 결정 요청: 사용자가 지금 골라야 할 정책을 명확하게 묻는다.

독립적인 질문은 관련 맥락과 함께 묶고, 앞선 답에 따라 달라지는 질문은 순서대로 묻는다. 질문 도구를 쓰면 선택지의 의미가 도구 화면에서도 해소되게 쓴다. 도구가 없으면 대화로 묻는다. 답이 없으면 미정인 정책을 임의의 기본값으로 구현하지 않는다. 결정과 무관한 조사·작업은 계속할 수 있다. 답은 설계에 반영하고, 다음 질문은 남은 쟁점이나 재검토할 근거에 연결한다.

Example: shared task deletion

현재 개인 할일은 삭제하면 완전히 사라집니다. 공유 목록은 여러 참여자가 같은 할일을 보기 때문에, 기존 방식을 그대로 적용하면 한 사람의 삭제가 다른 사람의 작업도 없애게 됩니다. 공유 할일의 삭제 의미는 아직 정해지지 않았습니다.

모두에게 삭제: 삭제하면 모든 참여자의 목록에서 사라집니다. 공동 목록을 정리할 수 있지만 다른 참여자가 사용 중인 할일도 사라집니다. 누가 이 동작을 할 수 있는지도 정해야 합니다.

내 목록에서만 숨김: 다른 참여자는 계속 보고 작업할 수 있습니다. 각자 목록을 정리할 수 있지만 이 동작으로 공동 할일 자체를 없애지는 못합니다.

공유 할일에서 삭제는 어느 동작이어야 하나요?

Present a proportionate design

도메인 동작과 범위를 새로 합의해야 하면 사용자가 판단할 수 있는 짧은 설계를 제시한다. 작은 변경은 대화로 충분하다. 여러 흐름이나 장기 유지할 결정이 있으면 문서로 남긴다. 설계는 기능·시나리오·완료 기준을 설명한다. 파일·함수·작업 순서를 승인 대상으로 올리지 않는다. 실행에는 제안한 정책·범위에 대한 사용자 합의가 필요하다. 대화에서 합의하고 구현을 요청했다면 별도 문서 승인 단계는 두지 않는다.

Design contents

문서는 맥락 없는 독자가 서비스 동작과 중요한 결정을 이해할 수 있게 쓴다. 프로젝트 고유 용어는 풀고, 근거는 그것을 쓰는 곳에 붙인다.

• Scope: 목표와 이번에 바꾸는 기능.
• User flows and scenarios: 적용되는 경로에서 사용자가 관측할 결과.
• Acceptance criteria: 완료를 참·거짓으로 판정할 기준과 확인 방법. 테스트 통과가 어떤 서비스 결과를 검증하는지도 드러낸다.

다음 절은 필요한 것만 둔다. 고정 절을 채우기 위해 해당 없음 문단을 만들지 않는다.

• Non-goals: 독자가 범위를 오해할 수 있는 제외 사항.
• Design: 중요한 기술 결정과 근거·대가. 국소적인 구현 방법은 실행자가 정한다.
• Global constraints: 정확한 버전·값·형식 등 전역 제약.
• Compatibility and migration: 기존 데이터·공개 계약·하류 사용자에 미치는 영향.
• Cross-cutting concerns: 이번 변경과 관련된 보안·프라이버시·운영 등 요구.
• Alternatives considered: 다른 시스템 경계·데이터 모델·공개 인터페이스·실행 모델을 고르지 않은 이유.

example-design.md는 문서 예시다. 설계 초안은 groundwork:design-review로 한 번 점검한다. 합의가 필요한 잔여 정책은 설명해 묻고, 확인하지 못한 사실은 남긴다.

Artifact paths

프로젝트에 기존 규약이 있으면 따른다. 없으면 docs/designs/DESIGN-NNNN-<topic>.md에 설계를, docs/artifacts/ARTIFACT-NNNN-proto.<ext>에 프로토타입을 둔다. 기존 설계의 최대 번호 다음 4자리 번호를 쓰고 같은 작업의 프로토타입은 번호를 공유한다. 설계는 created·updated 날짜를 가진 커밋 산출물이고 프로토타입은 커밋하지 않는다. 설계가 바뀌면 해당 문서를 고치고 updated를 갱신한다. 결정만 모으는 별도 문서를 만들지 않는다. 후속 설계가 앞 설계를 대체하면 원 문서에 후속 경로와 변경 내용을 남긴다.