cadence-plan

name	cadence-plan
description	결정 위험이 높거나 실행 범위가 크고, 신규 spec·도메인, 모호한 요구, 기존 시스템 제약, 추상화 판단을 검토할 때 사용한다.

cadence-plan

플랜 단계 결함 패턴 사전 차단용 4개 mandatory 정확도 체크. 회고에서 반복적으로 발견된 플랜 단계 실패 모드를 룰화한다.

4개 체크는 mandatory다. 4번의 사용자 게이트는 mandatory가 아니다.

언제 적용하나

다음 중 1+ 조건 충족 시 mandatory:

• 높은 결정 위험 또는 큰 실행 범위
• 신규 spec / specsheet draft 작성 (특히 새 도메인·모호 범위)
• 새 도메인 / 새 컴포넌트 / 새 라우트 추가
• 추상화 결정 (재사용 컴포넌트 분리, 헬퍼 추출 등)
• 모호한 요구 (server contract / 디자인 미확정) 진입
• mid-PR 스코프 변경 검토
• 기존 코드/문서/디자인/계약이 있는 영역에서 명시 요청을 반영

압축 대상: 결정 위험이 낮고 실행 범위도 작은 명백한 수정은 체크를 내부적으로 축약하고 결과만 보고한다.

제외 대상: 1줄 fix, 봇 follow-up, props 미세 조정, 명백한 typo.

Decision-Gating 연동

4개 영역은 정확도를 위한 내부 체크다. 각 영역의 종료는 사용자 게이트 사유가 아니다. 사용자에게 보이는 게이트는 using-cadence가 소유한다.

Context ─┐
Options ─┼─ 내부 정확도 체크 ─→ 승인 범위 안이면 계획·편집·검증 지속
Risk/OoS ┤
Verify ──┘
                         └─ 새 사용자 선택이 생길 때만 보고 후 정지

다음 경우에만 체크 결과를 decision gate로 올린다.

• 기존 시스템과 요청이 충돌하고 두 경로의 결과가 다름
• 실질적으로 유효한 옵션이 2개 이상이며 사용자 선택이 필요
• 위험을 수용하려면 범위 / 공개 계약 / 비가역 작업이 달라짐
• 검증 실패가 합의한 접근의 전제를 깨뜨림

단순히 context → options → risk → verification으로 phase가 바뀐다는 이유로 멈추지 않는다. 계획 전용 요청은 계획 산출물에서 끝나고, 구현 요청은 합의된 승인 범위 안에서 로컬 편집과 검증까지 이어간다.

큰 기계적 변경

결정 위험은 낮지만 실행 범위가 크면 사용자 게이트 대신 다음 경로를 사용한다.

1. 변경 기준을 내부적으로 정의한다.
2. dry-run 목록을 만든다.
3. 대표 표본을 내부 검토한다.
4. 의미 있는 예외를 보존한다.
5. 일괄 적용 후 전체 검증한다.

표본 기준이나 예외 처리에 새 사용자 선택이 있을 때만 보고 후 정지한다.

1. 컨텍스트 수집 (mandatory)

플랜 작성 전 다음 4가지를 모두 확인한다.

1-1. 관련 회고 스캔

• cwd 에 docs/retrospectives/INDEX.md 가 있으면 카테고리 매칭으로 관련 회고 발굴
• 매칭된 회고는 본문까지 정독, takeaway 를 플랜에 반영
• 회고 50+ 건 등 규모가 크면 Explore subagent 에 위임 ("관련 회고를 찾아 takeaway 를 정리해줘")
• 회고 시스템이 없는 프로젝트면 git log + 기존 PR 본문 스캔으로 대체

1-2. 기존 시스템 적합성 게이트

기존 코드/문서/디자인/계약이 있는 영역을 수정할 때는, 사용자 요청의 문자 그대로를 바로 구현하지 않고 먼저 같은 시스템 안의 가장 가까운 선례와 대조한다.

순서:

1. 변경 대상의 종류를 분류한다: UI / API contract / copy / validation / routing / workflow / architecture
2. 같은 화면군, 같은 도메인, 같은 계층, 같은 역할의 기존 구현을 찾는다
3. 사용자 요청과 기존 선례가 일치하는지 확인한다
4. 충돌하면 임의로 한쪽을 정답 처리하지 말고, "요청은 A인데 기존 패턴은 B"라고 짧게 보고한다
5. 명시 요청이 기존 패턴을 깨는 변경인지, 기존 패턴에 맞추는 변경인지 구분한 뒤 최소 변경으로 반영한다

발동 신호:

• "같게", "맞춰", "간격", "문구", "상태", "분기", "추가", "응답", "스키마", "레이아웃"처럼 기존 체계와 연결될 가능성이 있는 요청
• 여러 파일/도메인에 걸친 변경
• Linear/Figma/OpenAPI/기존 코드 중 2개 이상이 참조되는 작업
• 사용자가 "이미 해결된 걸 수도", "기존이랑 맞는지", "디자인 언어에 맞는지"라고 말한 경우

예시:

• UI QA에서 "divider 20px"이라고 되어 있어도, 먼저 같은 화면군 divider가 border인지 section divider인지 확인한다.
• API 필드 추가 이슈에서는 이슈 본문만 보지 말고 generated type, mock, formatter, 테스트 fixture까지 확인한다.
• validation 문구 수정에서는 schema만 보지 말고 submit 실패 처리와 toast 분기까지 확인한다.
• routing fallback에서는 URL depth만 보지 말고 기존 layout policy와 사용자가 실제 진입한 경로를 확인한다.

이 게이트는 기존 시스템을 무조건 정답으로 보라는 뜻이 아니다. 기존 시스템은 기준점이고, 사용자 명시가 그 기준을 의도적으로 바꾸는 요청일 수도 있다.

컴포넌트/패턴 검색 (grep-miss 방지)

대표 통점: "기존 X 컴포넌트 재사용 가능?" 을 사용자 확인 지점에 두면 grep 으로 못 찾는 자체 모듈을 한 답변으로 발견 (분산 호출 패턴은 name 검색만으로 안 잡힘).

• 프로젝트의 모듈 / 컴포넌트 디렉토리에서 유사 패턴 검색 (위치는 프로젝트마다 다름)
• 보고 / 옵션 제안에 기존 X 재사용 가능? 확인 지점을 포함 — 사용자 지식이 grep 보다 빠를 때 많음. 단, 특정 다지선다 도구로 묶지 말고 자유 응답을 열어둔다.

AST 검색 / 의존 그래프 분석 / 외부 contract 변경 감지 같은 도구별 자동화 (예: ast-grep, knip, openapi-diff 등) 는 별도 stack-특화 skill repo 또는 프로젝트 hook 에서 다룬다. cadence 본 repo 는 수동 검색 절차 만 정의.

1-3. 메모리 룰 cross-check

• 작업 영역의 관련 메모리 룰을 훑기 (cadence-ai-behavior 룰 + 프로젝트 L2 룰)
• 플랜이 룰과 충돌하면 룰 우선 또는 룰 갱신 제안

1-4. 스펙 ↔ 구현 대조 (done ≠ 구현 완성)

스펙시트 status: done 은 그 PR 시점에 닫혔다 는 뜻이지 모든 분기/매핑이 코드에 반영됐다 는 보장이 아니다. 다분기 매핑(N라벨 표 등)은 stub(예: 단일 필드만 반환)으로 닫히기 쉽다.

• done 스펙 영역을 건드릴 때 spec 본문 ↔ 실제 구현 함수를 대조한다. 스펙의 라벨/분기 표가 실제 코드에 다 있는지 해당 함수를 직접 읽는다.
• 특히 사용자가 표시/동작 버그를 제보 하면 "done 이니 맞겠지" 가정 말고 해당 표시·분기 함수부터 읽는다 (done stub 이 흔한 원인).
• 사례: 상태 라벨 표가 done 스펙에 닫혀 있는데 실제 formatter 는 raw status 만 반환하는 stub → 특정 상태에서 이전 라벨이 그대로 노출.

2. 옵션 탐색 (mandatory check)

단일 안 갇힘은 회고에서 반복 발견되는 실패 모드 (premature abstraction, stale spec 가정, 단일 결정 단정 톤). 다음을 강제한다.

2-1. 실질적 대안 확인

• 실질적으로 유효한 안이 2개 이상이면 추천 안 + 대안 1안 이상을 비교한다.
• 각 안의 장단점 / 비용 / 위험을 확인한다.
• 기계적 변경이나 기존 계약이 답을 고정하면 억지 대안을 만들지 않고 실질적 대안 없음으로 닫는다.
• 선택이 결과를 바꿀 때만 옵션을 사용자에게 노출한다.

2-2. Contrarian 질문 1개

플랜 작성 후 자문한다. 결정 위험이 있는 작업은 답을 플랜에 적고, 낮은 위험 작업은 내부 확인으로 충분하다.

"반대 가정이 사실이라면? 이 결정이 틀렸을 가능성은?"

예시:

• "spec 의 명시 endpoint 가 server contract 와 다르면?"
• "이 컴포넌트가 1곳만 쓴다고 가정했는데 grep 못 찾은 호출처가 있으면?"
• "이 추상화가 다음 PR 에서 깨질 가능성은?"

2-3. Decision artifact readiness

사용자에게 선택을 요청해야 할 때는 비교 산출물이 실제로 선택 가능한 상태인지 먼저 확인한다.

1. 각 선택지가 실제로 열리거나 렌더링되거나 실행된다.
2. 선택지 사이의 차이가 사용자가 관찰할 수 있는 형태로 드러난다.
3. 비교에 필요한 핵심 제약과 검증 결과가 준비되어 있다.
4. 검증 실패가 접근 전제를 깨면 선택을 요청하지 않고 범위 안에서 먼저 수정하거나 실패를 보고한다.

대표 증거:

• 시각·인터랙션: screenshot, DOM, canvas 크기·픽셀, 실제 조작 결과
• API·데이터: schema, 실제 호출 경로, 대표 응답, 데이터 소유권
• migration·일괄 변경: dry-run, 대표 표본, 예외 목록
• 문서·copy: 가장 가까운 선례와 실제 렌더링 또는 사용 위치

사용자가 결과를 확인할 수 없는 placeholder, 0x0 렌더링, 사실상 같은 선택지로 decision gate를 열지 않는다. 이는 새 승인을 추가하는 절차가 아니라 기존 게이트의 입력 품질 조건이다.

3. 위험 / 폐기 조건 / Out of scope (mandatory check)

머지 직전 발견되는 위험은 회수 비용이 크다. 계획 또는 spec 산출물이 있는 작업은 다음 3개를 명시한다. 낮은 위험의 기계적 작업은 최종 보고에 한 줄로 압축할 수 있다.

• 위험 (≥ 1) — 알려진 미해결 의존성, 외부 contract 변경 가능성, 회귀 가능 영역
• 폐기 조건 (≥ 1) — 어떻게 알아챌까 — 이 접근이 틀렸다고 판단할 시그널
• Out of scope — 본 작업/PR 에서 다루지 않을 항목 (별도 PR / follow-up). 봇 트리아지 비용 절감

4. 외부 검증 — 사다리 (Verification Ladder)

Eugene Yan 의 저렴 → 비싼 사다리 패턴 차용. 단일 layer 가 아니라 비용 효율적 escalation. 실패/disagree 시만 상위 layer 진입.

Review topology preflight

검증 layer를 고르기 전에 review unit을 정한다. plan task는 구현 순서와 인계를 위한 단위이며 자동으로 독립 리뷰 단위가 되지 않는다.

Review slice는 같은 위험·불변식·검증 증거로 함께 승인하거나 거부할 수 있는 변경 묶음이다. 다음 조건을 확인한다.

1. 인접 task가 같은 계약이나 아키텍처 불변식을 공유하면 하나의 slice 후보로 묶는다.
2. 한 task의 결함을 다른 task와 분리해 판단할 수 있고 reviewer가 서로 다른 결론을 낼 수 있을 때만 나눈다.
3. 파일 이동, import 갱신, format, 문구, 경로처럼 결정론적으로 판정 가능한 단계는 semantic slice를 만들지 않는다.
4. 공개 계약, 상태 소유권, 보안, 데이터, migration, 사용자 동작이 달라지는 경계는 별도 targeted slice로 둔다.
5. 누적 변경 사이 상호작용이 있을 때만 마지막 whole-change review를 추가한다.

변경 성격	기본 증거	semantic review
문구·경로·format·기계적 이동	정적 검사, diff 표본, 관련 test	기본 생략
같은 불변식을 공유하는 구조·통합 변경	관련 test, typecheck/build, 경계 검색	slice 완료 후 targeted 1회 후보
공개 계약·보안·데이터·migration	계약 증거, 실패 경로, rollback 조건	위험 경계마다 targeted 1회
여러 slice가 누적된 큰 변경	전체 회귀, 실제 runtime, 교차 경계 확인	누적 위험이 있을 때 whole-change 1회

reviewer 호출 수를 plan task, phase, commit 수에 맞추지 않는다. 하위 workflow가 task마다 review를 요구해도 사용자가 그 topology를 명시적으로 요청하지 않았다면 이 preflight 결과로 조정한다. 리뷰 단위와 위험 경계 회고

4-layer 구조

Layer	비용	자동/조건부	도구 예시
L1. 결정론 (mechanical)	토큰 0	자동 (post-edit hook 권장)	tsc / oxlint / oxfmt / ruff / build
L2. cheap semantic	저토큰, 1회	조건부 후보 (완료 보고 전 검토)	1차 보조 AI review (스펙 정합) — feedback_crosscheck 의 주 도구 → 보조 도구 1
L3. consensus	중토큰, 조건부	L2 disagree / 의심 시만	다른 모델 family 또는 PR review bot — 다중 리뷰 경로 합의
L4. 수동 inspection	사람 시간	L3 도 미해결 시 / 핵심 결정	사용자 직접 판단, 독립 리뷰의 플랜 텍스트 비판

운용 원칙

• L1 은 항상 통과해야 다음 단계 진입 — 빨간불에서 L2 호출 금지
• L2 가 OK 면 L3 호출 X — 비용 효율. L3 는 L2 가 disagree 또는 사용자 명시 요청 시만
• L4 는 판단 필요 한 결정 — 도메인 추상화 / 새 컴포넌트 / 새 라우트 / contract gap 의심 시
• 각 layer 결과는 합산이 아니라 게이트 — L1 통과 → L2 통과 → … 순차

검토·subagent 비용 비례

agent 수와 검토 횟수 자체는 신뢰도의 증거가 아니다. 기본 경로는 주 작업 경로 1개와, 필요할 때의 독립 semantic 검토 1개다.

• L1이 통과하고 1차 semantic 검토가 동의하면 같은 결론을 확인하기 위한 추가 agent를 호출하지 않는다.
• 추가 검토는 불일치, 높은 결정 위험, 큰 blast radius, 사용자 명시 요청이 있을 때만 연다.
• 단순 문구·경로·기계적 변경은 결정론적 검증과 표본 확인으로 닫는다.
• 재리뷰는 수정으로 판단이 달라질 load-bearing finding과 실제 변경 범위만 확인한다. style·format·경로 존재 여부처럼 결정론적으로 닫을 수 있는 잔여 항목 때문에 semantic reviewer를 다시 호출하지 않는다.
• Minor finding이 현재 slice의 전제를 깨지 않으면 기록 후 최종 검토에서 triage한다.
• 하위 workflow가 task마다 review, commit, 사용자 게이트를 요구해도 현재 review topology, Approval Scope, terminal intent가 우선한다.

여기서 게이트는 다음 검증 layer로 진입하는 내부 조건이다. 새 사용자 선택이 없으면 사용자 turn을 요구하지 않는다.

적용 시점

• post-edit (L1): 매 편집 후 자동 (프로젝트의 hook / lint-staged 등)
• review slice 완료 (L1 + 조건부 L2): slice 단위로 L1 은 수행한다. L2 는 semantic 불확실성·결정 위험 때문에 이득이 있고 보조 리뷰 경로가 설정되어 있거나, 사용자가 명시적으로 요청했을 때 실행한다.
• PR 머지 직전 (L1 + L2 + L3 조건부): 누적된 변경에 다시 한 번
• 큰 결정 (L4): 독립 리뷰의 플랜 단계 비판 — cadence-plan § 3 의 위험 명시와 결합

위험과 실행 범위별

결정 위험	실행 범위	적용 layer
낮음	작음	L1
낮음	큼	dry-run / 표본 검토 + L1
높음	작음	L1 + 필요 시 targeted L2
높음	큼	L1 + L2 + 조건부 L3 + 핵심 결정의 L4

이 사다리는 단일 모델 편향 회피 (feedback_crosscheck) 와 결합해 비용 효율적 다각도 검증 을 보장.

코딩 판단 원칙 (외부 stack-특화 skill)

플랜의 옵션 탐색 단계에 흔한 단축 경로 ("단언으로 풀자 / disable 로 막자 / types.ts 만들자 / 컴포넌트 분리하자") 가 나오면 자동 재검토 게이트 작동.

이런 코딩 판단 원칙 은 언어 / 프레임워크별 예시가 다르므로 cadence 본 repo 가 아닌 별도 stack-특화 skill repo 에서 다룬다 (예: frontend-skills / python-skills / go-skills 등). 본 repo 는 cross-stack 범용 만 담당.

해당 skill 이 설치되어 있으면 플랜 단계에서 동시 적용. 미설치 시 본 단축 경로 게이트만 약해질 뿐 다른 단계 작동에는 영향 없음.

스펙시트 작성 보조 렌즈 (lazy-load)

스펙시트는 탐색 → 결정 → 문서화 의 세 단계를 거친다. cadence-plan 은 결정권과 게이트를 담당하고, 외부 helper skill 은 필요한 순간에만 보조 렌즈로 로드한다. helper 가 설치되어 있지 않으면 아래 체크리스트를 본 skill 안에서 직접 수행한다.

렌즈	로드 시점	역할	금지
Brainstorming Lens (brainstorming, superpowers 계열 등)	요구가 모호하거나 첫 문제 정의 단계	가능한 해석 2-3개, 가장 작은 첫 PR 단위, 확인 질문 후보, 반대 가정 도출	바로 스펙시트 확정 / 구현 진입
Writing Lens (writing-skills, clarify 등)	결정된 내용을 스펙시트로 정리할 때	구현 가능한 명세로 재구성, facts / assumptions / TBD 분리, 읽기 쉬운 섹션화	아직 결정 안 된 가정을 매끈한 문장으로 확정처럼 포장
Hardening Lens (harden, audit, stack 특화 skill 등)	ready 전 또는 위험 큰 UI/API 흐름	실패 UI, edge case, 접근성, i18n, responsive, contract gap 체크	본 PR 범위를 몰래 확장

운용 원칙

• Lazy-load: 모든 스펙시트에 helper 를 자동 로드하지 않는다. 요구가 명확한 중간 작업은 cadence-plan 축약형만으로 충분하다.
• Decision before Writing: writing 계열은 formatter/editor이지 decision maker가 아니다. 새 사용자 선택이 필요한 결정만 먼저 합의한 뒤 문서화한다.
• TBD 보존: 불확실한 항목은 문장으로 숨기지 말고 ## TBD, ## 위험 / 폐기 조건, ## Out of scope 에 남긴다.
• 승인 범위 준수: 계획 전용 요청은 Plan / Writing에서 끝낸다. 구현 요청은 결정이 합의됐으면 Writing → 로컬 구현 → 검증을 이어갈 수 있다. phase 전환 자체로 게이트를 만들지 않는다.

산출물 형식 — 스펙시트 메타-구조

4개 정확도 체크가 문서 산출물로 필요하면 스펙시트 (specsheet) 형식으로 결정화한다. 프로젝트별 구체 어휘는 *프로젝트 안 _template.md*가 담당하고, 본 skill은 메타-구조만 정의한다.

4개 체크 → 스펙시트 매핑

플랜 단	산출물 위치 (스펙시트 섹션)
1단. 컨텍스트 수집	## 개요, ## 동작 / 변경 목록, ## 관련 회고 link
2단. 옵션 + Contrarian	## 동작 상세, ## 엣지 케이스
3단. 위험 / 폐기 / Out of scope	## TBD, ## 후속 작업 (별도 작업), ## 위험
4단. 외부 검증	## 검증 결과 (보조 도구 의견 요약), ## 구현 체크리스트 확정

스펙시트 메타-구조 (필수 섹션)

---
title: <한 줄 제목>
status: draft | ready | in-progress | done | revised
created: YYYY-MM-DD
updated: YYYY-MM-DD
related-retrospectives: [<link>, ...]
---

## 개요
<목표 1-2 문장 — 왜 이 작업을 하는가>

## 동작 / 변경 목록
- [ ] <동작 1>
- [ ] <동작 2>

## 동작 상세
### <동작 1>
- 사용자 흐름 / 입력 → 출력 / 에러 처리

## 공통 사항
- 진입 조건 / 이탈 동작 / 상태 흐름

## 엣지 케이스
- <Contrarian 질문 결과>

## TBD
- <해소 안 된 결정 — 모두 해소되면 status: ready>

## 위험 / 폐기 조건
- 위험: <≥ 1>
- 폐기 조건: <어떻게 알아챌까>

## Out of scope
- <본 작업에서 다루지 않을 항목>

## 구현 체크리스트
- [ ] <100% 시 status: done>

## 후속 작업 (별도 PR)
- [ ] <- PR #N>

## 관련 회고
- [<link to retrospective>]

lifecycle (선택 — 프로젝트가 정착 운용 시)

프로젝트가 디렉토리 lifecycle 을 운용하면 본 skill 은 그 컨벤션 따름:

status	위치 (예시)
draft / ready	backlog/
in-progress	in-progress/
done / revised	done/

위는 예시 — 각 프로젝트는 자기 lifecycle 따름.

위험 / 실행 범위와 스펙시트

결정 위험 / 실행 범위	스펙시트
낮음 / 작음	생략 가능. 최종 보고에 개요 + 변경 목록
낮음 / 큼	dry-run 기준과 검증 목록을 얇게 기록
높음 / 작음	결정과 위험을 플랜 요약으로 기록
높음 / 큼	스펙시트 권장. 새 도메인 / 공개 계약 / migration은 mandatory

회고와의 연결

작업 완료 후 학습할 점 이 있으면 cadence-retrospective 트리거. 스펙시트의 ## 관련 회고 섹션이 역방향 link — 회고가 어떤 스펙시트에서 나왔는지 추적 가능.

위반 시 결과

• 1번 (컨텍스트 수집) 누락 → 플랜 재작성. 회고 / 기존 컴포넌트 검색 누락은 단순 누락이 아니라 반복 비용 발생원
• 2번 (실질적 대안 확인 누락) → 사용자가 "다른 옵션은?" 묻기 전 자체 보완. 대안이 없으면 그 근거 명시
• 3번 (위험 / 폐기 / Out of scope 누락) → 머지 직전 회수 비용 위험

프로젝트별 적용 (Layer 분리)

본 skill 은 프로세스 만 정의. 룰 내용은 cwd 에서 동적 스캔:

• L2 (프로젝트 기술 컨벤션) — cwd 의 docs/ai-rules/, root config, 또는 동등 위치
• L3 (프로젝트 도메인 결정) — cwd 의 메모리, docs/specsheets/done/ 등

회고 / 스펙시트 구조가 정착된 프로젝트는 그 자산을 동적 활용. 회고가 없는 프로젝트는 git log + 기존 PR 로 대체.

발동 시 사용자 시그널

본 skill 작동 중 AI 응답에는 사용자 결정과 결과에 필요한 신호만 나타난다.

• "요청은 A인데 기존 패턴은 B" — 기존 시스템 충돌
• "옵션 A / B + 내 추천" — 실질적 선택이 있는 경우
• "실질적 대안 없음" — 기계적이거나 계약이 답을 고정한 경우
• "위험: ..." / "폐기 조건: ..." / "Out of scope: ..." — § 3 mandatory
• 큰 기계적 변경에서는 dry-run / 표본 검토 / 전체 검증 결과
• 새 사용자 선택이 없으면 내부 phase나 helper skill 이름은 출력하지 않음
• 산출물이 스펙시트 메타-구조 로 결정화 (개요 / 동작 목록 / 엣지 케이스 / TBD / 구현 체크리스트 / 후속 작업 / 관련 회고)
• 추상화 결정 시 "단언으로 풀자 / disable 로 막자 / types.ts 만들자 / 컴포넌트 분리하자" → 자동 재검토 (stack-특화 skill 설치 시)

미작동 시 → USAGE.md § 5 진단표 참조.

관련

• cadence-ai-behavior — AI 행동 통제 룰
• cadence-retrospective — 작업 완료/실패 후 회고 작성 가이드
• using-cadence — 승인 범위 + decision-gating
• USAGE.md — 시나리오별 사용 예시
• 프로젝트의 docs/retrospectives/INDEX.md — 회고 스캔 entry point (있는 경우)