gap-find

name	gap-find
description	여러 독립 역할(보안/정합성/기능갭/운영 등)로 프로젝트를 병렬 심사해 취약점·결함·기능갭을 발굴하고, 승인 시 파일-클러스터 배타분리로 병렬 반영까지 닫는 스킬. "취약점 찾아줘", "개선할 기능 찾아줘", "레드팀 해줘", "gap find", "다역할로 감사해줘" 같은 요청에 발동. 코드가 없는 설계 문서 단계에서도 동작한다.
user_invocable	true
tags	["security","audit","vulnerability","feature-gap","multi-agent","review"]
trigger	취약점/개선기능 발굴 요청 / 여러 역할로 프로젝트 감사 / 코딩 착수 전 마지막 게이트
version	1

Gap Find

한 명의 심사역이 아니라 서로 다른 렌즈를 가진 N개 역할로 프로젝트를 병렬 심사해 취약점·정합성 결함·기능 갭을 발굴하고, 승인 시 반영까지 닫는다.

doc-health-audit(문서 자체의 위생)과 구분된다 — 이건 프로젝트의 실질적 결함/공백(보안·로직 정합성·로드맵 누락·운영 리스크)을 본다. 코드가 아직 없는 설계 단계에서도 동작한다 — 오히려 그때 발견 비용이 가장 싸다.

Use When

• "취약점 찾아줘", "개선할 기능 찾아줘", "레드팀 해줘" 류 요청 (1차 트리거)
• 큰 설계/구현 단계 완료 직후, 코딩 착수 전 마지막 게이트
• 한 명의 시각으로는 놓치는 게 많다고 의심될 때 (보안만 보면 기능갭을, 기능만 보면 운영 리스크를 놓친다)
• 발견한 결함을 그 자리에서 반영까지 원할 때

표준 역할 세트 (프로젝트에 맞게 조정)

역할	렌즈	반드시 다룸	피함
보안 레드팀	인가/인증/데이터 노출 공격	RLS·인가 경계, 입력검증, 시크릿 관리	근거 없는 트집
정합성 감사	상태 전이·동시성·문서 간 모순	전이 완전성, 레이스 컨디션, 계약-머신 정합	문체 트집
기능 갭 헌터	로드맵/경쟁 대비 누락 시나리오	사용자 여정 커버리지, 기존 갭과 중복 확인	ROI 없는 기능 남발
운영 회복탄력성	장애 대응·관찰가능성·확장성	장애 복구 경로, 모니터링 공백, 병목	현재 규모에 안 맞는 오버엔지니어링

역할 수·조합은 도메인에 맞게 바꾼다. 각 역할은 서로 겹치지 않는 파일/주제 스코프를 받아야 독립적인 결과가 나온다.

Steps

1. Scope & Cluster(직접) — 역할별 담당 파일/문서를 배타적으로 분리. 코드가 없으면 설계문서(계약서/스펙/보안정책) 대상.
2. Find(저가 모델, N역할 병렬) — lens/must_emphasize/avoid를 명확히 박은 프롬프트로 동시 실행. 발견마다 파일:라인 근거 + 구체 시나리오 + 제안 강제.
3. Verify high-severity(직접) — P0/치명 발견은 원본을 직접 열어 대조. 서브에이전트의 "코드 버그" 판정이 실은 "범위 밖 설계 공백"일 수 있음 — 필요하면 원인 재해석. 여기는 절대 스킵 금지.
4. Report + Approve — 심각도(P0/P1/P2) 순 표 1개로 끝. 산문과 중복 금지. 반영 범위(전부/일부/보류) 확인.
5. Fix(고가 모델, 파일-클러스터 배타분리 병렬) — 승인 범위를 파일 겹침 없는 클러스터로 나눠 동시 반영. 허브 파일(INDEX·FEATURE-CONTRACT-MAP·GAP-MATRIX 등)은 단 하나의 클러스터만 소유, 나머지는 "무엇을 추가해야 하는지"만 보고.
6. Verify(직접) — 기존 검증 도구(npm run docs:check 등) 재실행. 신규 산출물이 기존 관례(candidate: 표기 등)와 맞는지 원본 대조. 허브 파일 등록 누락(예: docs/INDEX.md)은 직접 마무리.

클러스터링 규칙 (Fix 단계 무충돌 핵심)

• 클러스터는 파일 단위로 배타적이어야 한다 — 같은 파일을 두 클러스터가 동시에 쓰면 유실/충돌.
• 여러 발견이 같은 허브 파일(GAP-MATRIX.md, FEATURE-SPEC.md, FEATURE-CONTRACT-MAP.md, STORE-DEPENDENCY-MATRIX.md, docs/INDEX.md)을 요구하면 한 클러스터에 몰아준다.
• 신규 계약서 추가로 npm run docs:check가 깨질 수 있는 클러스터는 그 클러스터 자신에게 최종 self-check를 맡긴다(다른 클러스터 병렬 편집 중이면 스킵하고 메인이 마지막에 한 번 더 돈다).

모델 등급

• Find 단계는 병렬화·비용 절감 목적이므로 저가 모델(Haiku)로 충분하다.
• Fix 단계 모델 등급은 전역 에이전트 모델 규칙을 따른다: 메인 모델이 상위급이면 직접/병렬화 목적으로만 서브에이전트, 하위급이면 사용자 요청 시 상위 모델(Opus)로 격상.

Verify

• 각 발견에 파일:라인 근거가 있음 (추측 없음)
• P0/치명 발견은 원본 재대조 완료
• Fix 단계 클러스터 간 파일 겹침 0건
• docs/INDEX.md 등 허브 파일이 최종 갱신되어 신규 산출물이 discoverable함
• npm run docs:check / npm run docs:health가 반영 후에도 PASS

Failure / Fallback

• 허브 파일 경합이 많아 스코프 분리가 애매하면 클러스터 수를 줄이고 순차 실행으로 전환한다.
• Find 단계에서 셸 도구 환경 문제(예: ls가 빈 결과 반환)로 오탐하면, 재실행 전 find로 직접 사실을 확인해 에이전트에게 주입한다.
• 발견이 실은 의도된 설계 범위 제한이면 "버그"로 반영하지 말고 "제한을 명시적으로 문서화 + GAP-MATRIX 추적 항목 등록"으로 전환한다.

참조 문서

• docs/status/AGENT-OPS.md § 주간 보안 체크리스트 — 이 스킬의 보안 레드팀 역할과 연계
• docs/GAP-MATRIX.md — 기능 갭 헌터 역할이 참조/등록하는 로드맵