Squashed '.vendor/stage-pilot/' changes from 551777b..646bc1e
646bc1e feat(skill): review-discovery 스킬 추가 및 README 업데이트 git-subtree-dir: .vendor/stage-pilot git-subtree-split: 646bc1e9797f8e596923e4ddec1b8c15ed15b028
This commit is contained in:
@@ -0,0 +1,211 @@
|
|||||||
|
---
|
||||||
|
name: review-discovery
|
||||||
|
description: "Use when: reviewing an existing Discovery document for missing content, additional OQ candidates, internal consistency, duplication, unnecessary content, placeholder residue, and REQ handoff readiness without changing lifecycle state."
|
||||||
|
argument-hint: "예: dcy-001 또는 docs/discovery/dcy-001_20260424_topic.md"
|
||||||
|
user-invocable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
# Purpose
|
||||||
|
|
||||||
|
This skill reviews an existing Discovery document as a non-gating quality check before `confirm-discovery` or before human review. It looks for missing content, candidate open questions, internal inconsistencies, duplicated statements, unnecessary text, placeholder residue, and weak handoff readiness.
|
||||||
|
|
||||||
|
이 skill은 별도 lifecycle stage를 만들지 않는다. 기본 목적은 Discovery 품질을 점검하고 수정 우선순위를 정리하는 것이며, 문서 상태 전환이나 index 갱신은 수행하지 않는다.
|
||||||
|
|
||||||
|
# When to use
|
||||||
|
|
||||||
|
- `/review-discovery dcy-xyz` 형태로 Discovery 문서를 먼저 점검하고 싶을 때
|
||||||
|
- `confirm-discovery` 전에 누락, 중복, OQ 후보, 표현 불일치를 빠르게 정리하고 싶을 때
|
||||||
|
- Discovery 문서가 길어지면서 같은 내용이 여러 섹션에 흩어졌는지 확인해야 할 때
|
||||||
|
- 템플릿 잔여 문구, 불필요한 상세 구현 설명, 근거 없는 확정 표현이 남아 있는지 보고 싶을 때
|
||||||
|
- 사람이 수정할 항목과 AI가 바로 정리할 수 있는 항목을 분리해서 보고 싶을 때
|
||||||
|
|
||||||
|
# Inputs
|
||||||
|
|
||||||
|
- Discovery 식별자
|
||||||
|
- `dcy-001` 같은 prefix
|
||||||
|
- `dcy-001_20260424_topic-slug` 같은 전체 ID
|
||||||
|
- `docs/discovery/<DISCOVERY_ID>.md` 같은 직접 경로
|
||||||
|
- 대상 Discovery 문서 본문
|
||||||
|
- 필요 시 관련 저장소 문맥
|
||||||
|
- 현재 저장소의 관련 파일, 문서, 설정
|
||||||
|
- `docs/discovery/index.md`
|
||||||
|
- `docs/project-structure.md`, `docs/runtime-flows.md`
|
||||||
|
- 현재 시각 (KST)
|
||||||
|
|
||||||
|
# Core Rules
|
||||||
|
|
||||||
|
## 1. 역할 경계
|
||||||
|
|
||||||
|
- 이 skill은 review helper이며, active SDLC 단계로 취급하지 않는다.
|
||||||
|
- 아래 항목은 수정하지 않는다.
|
||||||
|
- `# 0. 문서 상태`의 `상태`
|
||||||
|
- `# 11. Discovery Freeze`의 `Handoff Decision`, `Ready for REQ Drafting`, `Confirmed By`, `Confirmed At (KST)`
|
||||||
|
- `docs/discovery/index.md`
|
||||||
|
- 이 skill은 REQ 생성, 승인, 상태 승격을 하지 않는다.
|
||||||
|
- 사실 관계를 바꾸는 추정성 수정은 하지 않는다. 근거 없는 항목은 finding 또는 OQ 후보로 남긴다.
|
||||||
|
- 사용자가 단순 검토만 요청한 경우 결과는 findings-first로 보고한다.
|
||||||
|
- 사용자가 `정리`, `수정`, `보강`, `반영`까지 명시한 경우에만 의미 변화가 없는 경미한 편집을 수행할 수 있다.
|
||||||
|
|
||||||
|
## 2. 기본 검토 축
|
||||||
|
|
||||||
|
반드시 아래 항목을 검토한다.
|
||||||
|
|
||||||
|
### 2-1. 누락 항목
|
||||||
|
|
||||||
|
- 템플릿 기준으로 필요한 섹션과 핵심 내용이 빠지지 않았는지 확인한다.
|
||||||
|
- 빈 bullet, `TBD`, `{{...}}`, `필요 없으면 삭제` 잔여 문구를 누락 또는 미정리 항목으로 본다.
|
||||||
|
- 아래 핵심 정보가 약하거나 비어 있으면 finding으로 기록한다.
|
||||||
|
- 문제의 현재 상태와 기대 상태
|
||||||
|
- 핵심 변경 항목과 영향 범위
|
||||||
|
- FR/NFR와 범위 경계
|
||||||
|
- 리스크, 가정, 성공 기준
|
||||||
|
- REQ handoff 전 확인 기준
|
||||||
|
- 단, `# 2. 요구사항 판정 결과`가 `완전 중복`이면 템플릿 가이드에 따라 이후 섹션 축약을 허용한다. 이 경우 `# 9. 파일 처리 결과`까지의 중복 판정 근거와 참조만 충분한지 본다.
|
||||||
|
|
||||||
|
### 2-2. 추가 OQ 후보
|
||||||
|
|
||||||
|
- 아래 조건이면 새 OQ 후보를 제안한다.
|
||||||
|
- 범위 경계가 모호해 In Scope/Out of Scope가 흔들리는 경우
|
||||||
|
- 성공 기준은 있는데 측정 방식이나 데이터 출처가 없는 경우
|
||||||
|
- 리스크 완화 책임자나 판단 주체가 비어 있는 경우
|
||||||
|
- 외부 정책, 외부 시스템, 운영 절차, 승인자 결정이 필요한데 본문에 근거가 없는 경우
|
||||||
|
- 서로 다른 섹션이 충돌해서 사람 판단 없이는 확정할 수 없는 경우
|
||||||
|
- 이미 다른 섹션에서 답이 있는 질문은 OQ로 늘리지 말고, answered cleanup 대상으로 분류한다.
|
||||||
|
- 사소한 문장 다듬기나 서식 문제는 OQ로 만들지 않는다.
|
||||||
|
|
||||||
|
### 2-3. 문서 일관성
|
||||||
|
|
||||||
|
- 이슈명, 핵심 변경, FR/NFR, 범위 경계, 성공 기준, Freeze rationale 사이의 용어와 범위가 일치하는지 확인한다.
|
||||||
|
- `# 4. 이번에 정의할 변경`, `# 5. 요구사항 목록`, `# 6. 리스크/가정 목록`, `# 7. 초기 성공 기준`, `# 8. REQ로 넘기기 전 확인 체크`, `# 10. 사용자 결정 필요 항목 요약`, `# 11. Discovery Freeze`의 연결 관계를 본다.
|
||||||
|
- `Open` OQ가 남아 있는데 Freeze가 사실상 진행 가능처럼 읽히는지 확인한다.
|
||||||
|
- 문서 안에서 같은 개념을 서로 다른 이름으로 부르는 경우 정규화 필요 finding으로 기록한다.
|
||||||
|
|
||||||
|
### 2-4. 중복 제거 대상
|
||||||
|
|
||||||
|
- 같은 사실이나 요구를 여러 섹션에서 반복하는지 찾는다.
|
||||||
|
- 중복은 아래 세 종류로 분류한다.
|
||||||
|
- 완전 중복: 문장만 다르지만 의미가 같은 경우
|
||||||
|
- 부분 중복: 핵심은 같고 세부만 다른 경우
|
||||||
|
- 잘못된 재기술: 상위 요약과 하위 상세가 서로 다른 말을 하는 경우
|
||||||
|
- 중복이 있으면 어떤 섹션을 source of truth로 둘지 함께 제안한다.
|
||||||
|
|
||||||
|
### 2-5. 불필요한 내용
|
||||||
|
|
||||||
|
- Discovery 단계에 필요 없는 구현 디테일, 과도한 알고리즘 설계, 배포 절차 상세, 이미 결정된 이력 서술을 찾는다.
|
||||||
|
- 현재 반복의 문제 정의와 성공 기준에 기여하지 않는 배경 설명은 삭제 또는 압축 후보로 본다.
|
||||||
|
- 템플릿 가이드 문구, 예시 텍스트, 삭제 예정 placeholder 설명이 본문에 남아 있으면 제거 대상으로 본다.
|
||||||
|
|
||||||
|
## 3. 추가 검토 항목
|
||||||
|
|
||||||
|
사용자 요청 외에도 아래를 함께 본다.
|
||||||
|
|
||||||
|
### 3-1. 근거와 사실 일치성
|
||||||
|
|
||||||
|
- 문서가 현재 저장소 상태를 서술하는 경우, 그 주장에 직접 관련된 파일이나 문서와 모순이 없는지 확인한다.
|
||||||
|
- 저장소 확인은 문서의 핵심 주장과 직접 연결된 범위만 탐색한다. 구현 전체를 감사하지는 않는다.
|
||||||
|
- 저장소 근거와 충돌하는 서술은 높은 우선순위 finding으로 기록한다.
|
||||||
|
|
||||||
|
### 3-2. 실행 가능성과 측정 가능성
|
||||||
|
|
||||||
|
- FR/NFR, 성공 기준, 체크 항목이 다음 단계에서 실제 REQ/검증 항목으로 이어질 정도로 구체적인지 본다.
|
||||||
|
- `개선한다`, `지원한다`, `정리한다`처럼 모호한 동사만 있고 판정 기준이 없으면 구체화 필요 finding으로 기록한다.
|
||||||
|
- 성공 기준은 가능한 한 측정 방식과 데이터 출처에 연결되어야 한다.
|
||||||
|
|
||||||
|
### 3-3. 플레이스홀더 위생
|
||||||
|
|
||||||
|
- 사용자 결정이 필요한 placeholder와 단순 미정리 placeholder를 구분한다.
|
||||||
|
- 같은 의미의 placeholder가 본문과 `# 10. 사용자 결정 필요 항목 요약`에 중복으로 남아 있으면 정리 대상으로 본다.
|
||||||
|
- 이미 문서 근거로 해소 가능한 placeholder는 unresolved로 방치하지 않는다.
|
||||||
|
|
||||||
|
## 4. 허용되는 편집 범위
|
||||||
|
|
||||||
|
사용자가 수정까지 요청한 경우에만 아래 경미한 편집을 허용한다.
|
||||||
|
|
||||||
|
- 중복 문장 삭제 또는 압축
|
||||||
|
- 템플릿 잔여 문구 제거
|
||||||
|
- 번호, 체크리스트, 링크, 용어 표기 일관성 정리
|
||||||
|
- 답이 이미 문서 안에 있는 OQ를 본문 반영 후 resolved cleanup으로 정리
|
||||||
|
- 의미 변화 없는 섹션 재배치
|
||||||
|
- 실제 내용이 바뀌었을 때 `마지막 갱신 시각(KST)` 갱신
|
||||||
|
|
||||||
|
아래는 이 skill로 수정하지 않는다.
|
||||||
|
|
||||||
|
- 새 요구사항 생성
|
||||||
|
- 범위 재정의
|
||||||
|
- 정책 확정
|
||||||
|
- 승인자 지정
|
||||||
|
- 상태 전환과 index 갱신
|
||||||
|
|
||||||
|
# Review Heuristics By Section
|
||||||
|
|
||||||
|
섹션별로 최소한 아래를 점검한다.
|
||||||
|
|
||||||
|
- `# 0. 문서 상태`
|
||||||
|
- 문서 ID, 이슈명, 시각 정보, 참조 필드가 자기모순 없는지 확인한다.
|
||||||
|
- `# 1. 계획 상태 요약`
|
||||||
|
- 현재 작성 배경과 이번 Discovery의 핵심 판단 포인트가 2줄 요약으로 드러나는지 본다.
|
||||||
|
- `# 2. 요구사항 판정 결과`
|
||||||
|
- 신규/유사/중복 판정과 근거가 실제 본문 범위와 맞는지 본다.
|
||||||
|
- `# 3. 문제점의 요약`
|
||||||
|
- 현재 상태, 기대 상태, 이해관계자, 시나리오가 왜 이 Discovery가 필요한지를 설명하는지 본다.
|
||||||
|
- `# 4. 이번에 정의할 변경`
|
||||||
|
- 변경 항목과 영향 범위가 `# 5` 요구사항과 연결되는지 본다.
|
||||||
|
- `# 5. 요구사항 목록`
|
||||||
|
- FR/NFR가 구분되어 있고 범위 경계가 충돌하지 않는지 본다.
|
||||||
|
- `# 6. 리스크/가정 목록`
|
||||||
|
- 리스크, 가정, OQ가 각각 역할에 맞게 쓰였는지 본다.
|
||||||
|
- `# 7. 초기 성공 기준`
|
||||||
|
- 측정 대상, 방식, 데이터 출처가 요구사항과 연결되는지 본다.
|
||||||
|
- `# 8. REQ로 넘기기 전 확인 체크`
|
||||||
|
- 체크 항목이 선언만 있고 판단 기준이 없는지 본다.
|
||||||
|
- `# 9. 파일 처리 결과`
|
||||||
|
- 참조 문서가 실제 검토 근거를 반영하는지 본다.
|
||||||
|
- `# 10. 사용자 결정 필요 항목 요약`
|
||||||
|
- DECIDE, CONFIRM, DATA가 실제 unresolved 항목과 맞는지 본다.
|
||||||
|
- `# 11. Discovery Freeze`
|
||||||
|
- review 결과와 무관하게 상태 전환 없이, 본문과 논리적 충돌만 점검한다.
|
||||||
|
|
||||||
|
# Execution Procedure
|
||||||
|
|
||||||
|
1. 입력에서 Discovery 문서 경로를 확정한다.
|
||||||
|
2. 대상 Discovery 문서를 읽고, 필요 시 `docs/discovery/index.md`와 직접 관련된 저장소 문맥을 읽는다.
|
||||||
|
3. 문서를 `중복 판정으로 축약 가능한 문서`인지 `정상 Discovery 검토 대상`인지 먼저 분류한다.
|
||||||
|
4. 위 `기본 검토 축`과 `추가 검토 항목` 기준으로 findings를 수집한다.
|
||||||
|
5. findings를 아래 우선순위로 분류한다.
|
||||||
|
- `blocking`: REQ handoff 또는 사실 관계에 직접 문제를 만드는 항목
|
||||||
|
- `major`: 지금 고치는 편이 좋은 구조/일관성/측정 가능성 문제
|
||||||
|
- `minor`: 표현, 중복, 서식, 경미한 cleanup 문제
|
||||||
|
6. 추가 OQ 후보가 있으면 기존 OQ와 중복 여부를 제거한 뒤 후보 목록으로 정리한다.
|
||||||
|
7. 사용자가 수정까지 요청한 경우에만 `허용되는 편집 범위` 안에서 경미한 cleanup을 수행한다.
|
||||||
|
8. 편집을 수행한 경우 `마지막 갱신 시각(KST)`만 갱신하고, 상태 전환 없이 종료한다.
|
||||||
|
9. 최종적으로 findings, OQ 후보, auto-fix 결과, 다음 추천 행동을 보고한다.
|
||||||
|
|
||||||
|
# Output Expectations
|
||||||
|
|
||||||
|
작업이 끝나면 아래 내용을 보고할 수 있어야 한다.
|
||||||
|
|
||||||
|
- 대상 `DISCOVERY_ID`와 문서 경로
|
||||||
|
- 전체 판정
|
||||||
|
- `양호, 바로 confirm-discovery 검토 가능`
|
||||||
|
- `경미한 정리 필요`
|
||||||
|
- `추가 보강 필요`
|
||||||
|
- `문서 구조 또는 사실 관계 재정비 필요`
|
||||||
|
- severity별 findings 목록
|
||||||
|
- 새 OQ 후보 목록
|
||||||
|
- 중복/불필요 내용 정리 제안
|
||||||
|
- 자동 정리한 항목 목록(수정 요청이 있었을 때만)
|
||||||
|
- 다음 추천 행동
|
||||||
|
- `confirm-discovery` 진행
|
||||||
|
- Discovery 문서 추가 수정 후 재검토
|
||||||
|
- 범위가 바뀌어 `new-discovery` 또는 `change-req` 판단 필요
|
||||||
|
|
||||||
|
# Validation
|
||||||
|
|
||||||
|
완료 전에 아래를 확인한다.
|
||||||
|
|
||||||
|
- 대상 경로가 실제 Discovery 문서를 가리키는지 확인한다.
|
||||||
|
- `완전 중복` 예외를 제외하고, 누락 판단이 템플릿 구조와 충돌하지 않는지 확인한다.
|
||||||
|
- 제안한 OQ가 이미 본문이나 다른 섹션에서 답을 가진 항목이 아닌지 확인한다.
|
||||||
|
- 같은 finding을 누락/중복/불필요 항목에 중복 보고하지 않았는지 확인한다.
|
||||||
|
- 수정이 있었다면 상태 전환 값과 `docs/discovery/index.md`가 바뀌지 않았는지 확인한다.
|
||||||
|
- 저장소 사실 관계와의 충돌을 지적했다면 최소 한 개 이상의 직접 근거가 있는지 확인한다.
|
||||||
@@ -205,6 +205,7 @@ Discovery는 구현 완료 상태를 표현하는 단위가 아니다. Discovery
|
|||||||
baseline 초기화 이후 사용자 요청, 운영 피드백, issue 입력을 실제 변경 주제의 Discovery 초안으로 만든다.
|
baseline 초기화 이후 사용자 요청, 운영 피드백, issue 입력을 실제 변경 주제의 Discovery 초안으로 만든다.
|
||||||
2. `confirm-discovery`
|
2. `confirm-discovery`
|
||||||
Discovery를 저장소 현실과 대조하고 REQ drafting 가능 상태로 `confirmed` 전환한다.
|
Discovery를 저장소 현실과 대조하고 REQ drafting 가능 상태로 `confirmed` 전환한다.
|
||||||
|
선행 품질 점검이 필요하면 보조 helper인 `review-discovery`로 누락, OQ 후보, 중복, 불필요 서술을 먼저 정리할 수 있다. 이 helper는 상태 전환 없이 review만 수행한다.
|
||||||
3. `draft-req`
|
3. `draft-req`
|
||||||
confirmed Discovery에서 승인 가능한 REQ 문서를 만든다.
|
confirmed Discovery에서 승인 가능한 REQ 문서를 만든다.
|
||||||
4. `confirm-req`
|
4. `confirm-req`
|
||||||
|
|||||||
Reference in New Issue
Block a user