| name | doc-verifier |
| description | Verify documentation accuracy and completeness against source code. Use when checking if existing docs match code behavior, after doc-writer generates docs, or when reviewing PRs with doc changes. Use for (1) comparing generated docs vs actual source, (2) detecting stale/incorrect docs, (3) verifying API reference accuracy, (4) pre-PR doc quality check. SKIP for code review without docs, or for creating new docs (use doc-writer). |
doc-verifier
기존 문서와 소스 코드를 비교해 정확성·완전성을 검증한다.
역할
기존 문서와 소스 코드를 3-Pass(존재/동작/완전성)로 대조해 STALE/INCORRECT/MISSING 이슈를 판정하는 검증자. 신규 문서 생성은 하지 않는다(그건 doc-writer 담당).
컨텍스트
/doc-writer 실행 직후 생성물 검증, PR 리뷰 시 docs/ 변경 대응 소스 대비 검증, 또는 정기 문서 감사에서 호출. 입력은 문서 파일 + 대응 소스 파일/디렉토리.
출력
PASS/WARN/FAIL 판정 + 이슈 목록 표(유형/위치/설명/권고). STALE 이슈 존재 시 FAIL.
Quick Start
/doc-verifier <doc-file.md> --source <source-file>
/doc-verifier <doc-file.md> --source <source-dir> --type api|module|skill
실행 흐름
Step 1. 대상 로드
- 문서 파일 Read
- 소스 파일/디렉토리 Read
- 문서 유형 결정 (api / module / skill / agent / pipeline)
Step 2. 3-Pass 검증
Pass A — 존재 확인
문서에 기술된 항목이 소스에 실제 존재하는가:
- 함수명·파라미터명·반환 타입 → 코드에서 grep 확인
- 엔드포인트 경로 → 라우터 파일 확인
- 필드명·스키마 → 타입 정의 파일 확인
존재하지 않는 항목 = STALE 이슈.
Pass B — 동작 확인
기술된 동작이 실제 구현과 일치하는가:
- 파라미터 기본값 → 소스 확인
- 에러 처리 분기 → 코드 흐름 확인
- 예시 코드 → 실제 호출 가능 여부 확인
불일치 항목 = INCORRECT 이슈.
Pass C — 완전성 확인
소스에 있는 주요 요소가 문서에 누락되지 않았는가:
- public 함수 중 미문서화된 것
- 중요 파라미터 누락
- 에러 케이스 미기술
누락 항목 = MISSING 이슈.
Step 3. 판정
PASS: 이슈 없음 또는 MISSING MINOR만
WARN: MISSING MAJOR 1개+ or INCORRECT 이슈 (동작 오류)
FAIL: STALE 이슈 (존재하지 않는 내용 기술)
Step 4. 결과 출력
## 검증 결과
**판정**: PASS / WARN / FAIL
**대상**: <doc-file> vs <source-file>
### 이슈 목록
| 유형 | 위치 | 설명 | 권고 |
|------|------|------|------|
| STALE | §파라미터 userId | 소스에서 id로 변경됨 | 문서 수정 |
| MISSING | — | onError 콜백 미기술 | 섹션 추가 |
| INCORRECT | §예시 L12 | timeout 기본값 1000, 문서는 500 | 수정 필요 |
Inversion 검증
PASS 판정 직전 반전 체크:
- "문서가 맞다"는 이유 3가지 → 각각 "왜 틀릴 수 있나?" 확인
- 소스가 최근 변경됐을 가능성 → git log 확인 권고
- 문서가 다른 버전 기준일 가능성 → 파일 상단 날짜/버전 확인
활용 시점
/doc-writer 실행 직후 → 생성된 문서 즉시 검증- PR 리뷰 시
docs/ 변경 포함 → 대응 소스 파일 대비 검증
- 정기 문서 감사 →
docs/ 폴더 전체 스캔
참조
- 문서 생성:
/doc-writer
- spec-compliance-checker (FR 레벨 검증):
~/forge/.claude/skills/spec-compliance-checker/SKILL.md
