ask-user-question-rules

name	ask-user-question-rules
description	AskUserQuestion 호출 시 질문/옵션 작성 규칙. 다른 스킬이 prerequisite로 로드하여 사용. 사용자가 "무슨 말이야?"로 되묻거나 "충분하다"만 누르는 의례화 패턴 차단.

AskUserQuestion 작성 규칙

이 규칙은 /frame, /decide, /verify 등 사용자에게 결정을 묻는 모든 스킬에 자동 적용된다.

AskUserQuestion은 특정 UI 컴포넌트만을 뜻하지 않는다. Pi 환경에서 native interactive UI가 없거나 약하면 번호형 텍스트 메뉴로 같은 의사결정 게이트를 구현한다.

과거 분석에서 다음 어색한 패턴들이 확인됐다. 이 규칙을 어기면 사용자가 "무슨 말이야?"로 되묻거나, "충분하다"만 누르는 의례화가 발생한다.

---

질문 작성 규칙

AskUserQuestion은 “짧은 질문만 던지는 도구”가 아니다. 질문 제목은 짧게 유지하되, 사용자가 무엇을 판단해야 하는지 알 수 있도록 판단 맥락 카드를 함께 제공한다.

규칙	좋은 예	나쁜 예
짧은 질문 제목 + 판단 맥락 카드	제목: "검증 범위 선택" + 현재 이해/막힌 결정/추천/선택 후 변화	"어떻게 할까요?"만 출력
맥락은 구조화해서 보여주기	현재 이해 / 막힌 결정 / 왜 중요한가 / 추천 / 선택 후 달라지는 것 / 질문	배경을 생략하거나 긴 산문으로 뭉개기
하나의 결정만 묻기	"guard 위치를 어디까지 둘까요?"	"guard 위치 + 테스트 범위 + 후속 PR 여부" 동시 결정
결정 결과가 달라져야 함	선택마다 frame/decision/verify/구현이 달라짐	선택해도 같은 행동으로 귀결

판단 맥락 카드 기본형

질문 제목: {짧은 제목}

현재 이해:
- {코드/문서/사용자 발화로 확인한 사실}
- {아직 가정인 부분은 가정이라고 표시}

막힌 결정:
{지금 사용자가 선택해야 다음 행동/성공 기준이 달라지는 지점}

왜 중요한가:
{선택에 따라 달라지는 구현 범위, 검증 축, 위험, 롤백 비용}

추천:
{추천안이 있으면 이유와 함께 제시. 없으면 이 섹션을 생략}

선택 후 달라지는 것:
- A를 고르면: {달라지는 점}
- B를 고르면: {달라지는 점}

질문:
{한 가지 결정 질문}

규칙:

• 질문 제목만 짧게 쓰고 맥락 카드를 생략하면 실패다.
• 이미 본문/Studio update로 같은 맥락 카드가 바로 위에 렌더링돼 있으면 ask tool의 question은 짧은 제목만 써도 된다. 단, 맥락 카드 없이 제목만 단독으로 묻지 않는다.
• TFT Studio 같은 UI 도구에서는 긴 맥락 카드를 markdown/본문 영역에 두고, question 필드는 짧은 제목 한 줄로만 보낸다. question에 카드 전체를 넣어 타이틀처럼 렌더링되게 만들지 않는다.
• light 작업도 최소한 현재 이해 / 막힌 결정 / 선택 후 달라지는 것은 보여준다.

---

Pi text-mode fallback

인터랙티브 선택 UI를 사용할 수 없으면 아래 형식을 사용한다.

질문 제목: 검증 축 선택

현재 이해:
- 이번 변경은 UI와 데이터 저장 경로를 모두 건드립니다.
- 전체 verify-report를 바로 돌리면 비용이 크므로 먼저 닫을 축을 골라야 합니다.

막힌 결정:
어떤 축을 먼저 PASS 증거로 닫을지에 따라 실행할 검증과 캡처 범위가 달라집니다.

선택 후 달라지는 것:
- UI 동작: 화면 캡처/사용자 플로우를 먼저 확인
- 데이터 정합성: 저장/조회/API 응답을 먼저 확인
- 권한 경계: role별 접근 가능/불가 조건을 먼저 확인
- 범위 축소: 이번 PR에서 제외할 항목을 먼저 확정

질문:
어떤 검증 축을 우선할까요?

1. UI 동작 — 사용자가 보는 흐름을 캡처로 확인
2. 데이터 정합성 — 저장/조회/API 응답을 우선 확인
3. 권한 경계 — 접근 가능/불가 조건을 우선 확인
4. 범위 축소 — 이번 PR에서 제외할 항목을 먼저 확정

답은 번호로 주세요. 예: `1` 또는 `1,3`

규칙:

• 사용자가 1, 2, 1,3처럼 답하면 해당 option을 선택한 것으로 간주하고 바로 진행한다.
• multiSelect: true에 해당하는 질문만 쉼표 복수 선택을 허용한다.
• 번호는 표시 수단일 뿐이다. options 자체는 여전히 상호 배타적이거나, multiSelect라면 서로 독립적인 행동이어야 한다.
• 번호 답변을 받은 뒤 같은 질문을 다시 자연어로 확인하지 않는다.
• 사용자가 번호 대신 텍스트로 정정하면, 정정 의도로 해석하고 필요한 만큼 patch한다.

---

(명백) 근거가 있는 질문

/frame에서 목표·범위·성공 기준·검증 축을 좁힐 때는 AI가 보기엔 명백한 추천안도 묻는다. 이때 (명백: ...)은 질문을 생략하는 면죄부가 아니라, 사용자가 “내가 놓친 게 있나?”라고 혼동하지 않도록 판단 근거를 보여주는 주석이다.

질문 제목: 범위 선택

현재 이해:
- 요청의 핵심은 버튼 노출 조건입니다.
- 다만 실패 메시지 포함 여부에 따라 성공 기준과 검증 범위가 달라집니다.

막힌 결정:
직접 증상만 고칠지, 실패 경로까지 이번 성공 기준에 포함할지 정해야 합니다.

추천:
(명백: 실패 메시지까지 포함해야 사용자가 보는 취소 흐름이 닫힙니다.)
2번을 추천합니다.

선택 후 달라지는 것:
- 1번: 버튼 조건만 테스트하고 실패 메시지는 범위 밖으로 남김
- 2번: 버튼 조건과 실패 메시지를 함께 success criteria에 넣음
- 3번: 예약 상태 전환 전체를 추가 조사해 작업 무게가 커짐

질문:
이번 범위를 어디까지 잡을까요?

1. 버튼 노출 조건만 수정 — 최소 범위
2. 버튼 조건 + 실패 메시지까지 수정 — 추천
3. 예약 상태 전환 전체 점검 — 넓은 범위

규칙:

• (명백)은 질문 본문 앞에 두고, 옵션 안에는 결론처럼 넣지 않는다.
• 옵션은 여전히 선택 후 행동/계약이 달라져야 한다.
• 단순 사실 보고나 이미 처리된 검증 결과는 (명백)을 붙여도 질문으로 만들지 않는다.

옵션 작성 규칙

규칙	좋은 예	나쁜 예
짧은 명령형 또는 짧은 명사형 (30자 이내 권장)	"그대로 진행 / 재고 / 멈춤"	"차단상태에서 외부 X 재수신 → PopConfirm 두 번 노출 가능 (사용자 혼란). 현재 자주 발생 안 됨."
옵션 형식 통일	모두 명령형: "진행 / 재고 / 멈춤"	진술문 + 명령형 혼합
옵션 안에 결론 미리 적기 금지	"옵션 A — 처리 방식 1"	"옵션 A — 처리됨 (이미 코드에 반영)"
상호 배타 (mutually exclusive)	"A / B / C" 명확히 다른 선택	"A / A의 변형 / 절충" 같은 미묘한 차이
옵션 4개 이내 권장	2~4개	5개 이상 (인지 부담)
사실 진술을 옵션으로 만들지 않음	"이 시나리오를 처리할까요?" + [예/아니오/follow-up]	"이 시나리오는 자주 발생 안 함" (이건 옵션 아니라 진술)
"충분하다 — 다음 단계로 진행" 같은 통과용 옵션 금지	검증 결과는 본문에 보고, 사용자 결정 필요한 것만 옵션화	처리된 항목 나열 + "충분하다"

---

Productive Resistance / 도전 질문 작성 규칙

도전 질문 만들 때:

• 반론은 짧고 구체적으로 쓴다. 판단에 필요한 부연은 판단 맥락 카드에 포함한다.
• 구체적 시나리오 1개로 좁힘. "여러 잠재 위험" 나열 금지.
• /frame에서는 “성공 기준이 모호한가 / 롤백 비용 큰 선택은 뭔가 / 무엇을 안 할지 정했나”를 흔드는 독립 질문으로 사용한다.
• /decide에서는 모든 결정에 tradeoff challenge를 수행하되 low/medium/high/ask_first 강도만 조절한다.
• 옵션은 항상 행동형으로 쓴다: frame에서는 [성공 기준에 추가 / 범위 밖으로 명시 / 먼저 탐색], decide에서는 [선택 유지 / 보완 후 유지 / 재고 / frame으로 돌아가기]처럼 선택 후 canonical 기록이 달라져야 한다.
• 단순한 확신 확인은 금지한다: “괜찮나요?”가 아니라 어떤 트레이드오프를 수용·완화·재고할지 묻는다.

---

한국어 검수

스킬 안에서 한국어를 생성할 때:

• 영어 직역체 금지: "일이 나면" (X) → "발생하면" (O)
• 자체 신조어/축약어 금지: "쏼리" (X) → "쿼리" (O)
• 일반 한국어 어휘만 사용. 모르는 단어는 풀어 쓰기.
• 옵션 마지막 마침표/구두점 통일 (있으면 모두, 없으면 모두 없음)
• 명사/동사 끝맺음 일관성 (예: "...하기" / "...해" / "...진행" 중 하나로)

---

메뉴 중복 방지

같은 세션에서 동일한 메뉴를 연속 두 번 띄우지 않는다.

• 직전 AskUserQuestion의 옵션 셋과 현재 옵션 셋이 같으면 → 그 메뉴를 건너뛰고 진행
• 만약 사용자 정정이 필요해서 다시 띄워야 하면, 질문에 변화 사유를 명시: "이전 옵션에서 X를 보완하여 다시 묻습니다:"

---

옵션 0개 케이스 — 메뉴 자체 안 띄움

검증/엣지 케이스 분류 결과 모든 항목이 처리됨이면:

• AskUserQuestion 자체를 호출하지 않음
• 결과를 본문에 표로 보고하고 다음 단계로 직행
• "확인 의례"를 위해 가짜 옵션을 만들지 않음

---

자가 점검 체크리스트

AskUserQuestion 호출 직전 다음 자문:

1. ☐ 짧은 질문 제목과 판단 맥락 카드가 함께 있는가?
2. ☐ 현재 이해, 막힌 결정, 왜 중요한가, 선택 후 달라지는 것이 드러나는가?
3. ☐ 옵션이 모두 동일한 형식(명령형/명사형 통일)인가?
4. ☐ 옵션 안에 결론(처리됨/무관/부적용)이 적혀 있지 않은가?
5. ☐ 옵션이 mutually exclusive한가?
6. ☐ 직전 메뉴와 옵션 셋이 다른가?
7. ☐ 옵션 4개 이내인가?
8. ☐ 한국어가 일반 어휘인가? (신조어/직역체/오타 없음)
9. ☐ 사용자가 정말로 결정해야 하는 것인가? (정해진 답을 묻고 있지 않은가?)

체크리스트 항목 중 하나라도 NO면 질문을 다시 작성한다.