Akshaysanthosh/docs-drift-check

Docs Drift Check

브랜치나 diff가 문서 드리프트(drift)를 만들었는지 확인하고, 검토할 가치가 있는 정확한 문서 파일과 용어를 지목합니다. 이 스킬은 광범위한 추측보다는 diff의 구체적인 증거에 편향되어야 합니다.

이 스킬을 사용할 때

• 사용자가 브랜치, PR 또는 로컬 변경 사항이 문서 업데이트가 필요한지 물을 때.
• diff가 API 라우트, CLI 플래그, 환경 변수, 설정 키, 설정 단계, 또는 문서에서 참조할 수 있는 파일/모듈 이름과 같은 사용자 지향 동작을 변경할 때.
• README, docs/, examples/, 온보딩 또는 설정 문서에서 드리프트를 검토하는 작업이 있을 때.

순수한 스타일 변경, 테스트 전용 변경, 또는 가시적인 동작 변경이 없는 명백한 내부 리팩터링에는 이 스킬을 사용하지 마십시오.

빠른 시작

1. 헬퍼를 실행합니다: bash .agents/skills/docs-drift-check/scripts/docs_drift_check.sh [base-ref]
2. 신호가 가장 강한 섹션을 먼저 읽습니다:
   • Potential renames (잠재적 이름 변경)
   • Likely env var changes (가능한 환경 변수 변경)
   • Likely CLI flag changes (가능한 CLI 플래그 변경)
   • Likely route or endpoint changes (가능한 라우트 또는 엔드포인트 변경)
   • Likely config changes (가능한 설정 변경)
3. 가장 가능성이 높은 문서 대상을 검사합니다:
   • README.md
   • docs/
   • examples/
   • 영향을 받는 기능 근처의 설정 또는 온보딩 문서
4. 짧은 결과를 반환합니다:
   • 위험 수준: low, medium, high
   • diff의 구체적인 증거
   • 영향을 받을 가능성이 있는 문서 파일
   • 권장 편집 또는 패치 계획

워크플로

1. 비교 기준 설정

• 사용자가 제공한 기본 참조(ref)를 선호합니다.
• 제공된 것이 없으면 헬퍼는 기본적으로 main을 사용합니다.
• 기본 참조가 없으면 명확히 말하고 올바른 브랜치 또는 비교 대상을 요청합니다.

2. 문서에 민감한 변경 사항 식별

신호가 강한 변경 유형에 집중합니다:

• 환경 변수
• CLI 플래그 및 명령어
• API 라우트 또는 엔드포인트
• 설정 키
• 이름이 변경된 파일 또는 모듈
• 설정 또는 온보딩 단계

결정적 1차 분석을 위해 헬퍼 스크립트를 사용하고, 필요한 경우 diff를 수동으로 검사합니다.

3. 코드 변경 사항을 문서와 비교

• 문서에서 이전 및 새로운 이름, 경로, 플래그, 라우트 및 설정 용어를 검색합니다.
• 전체 저장소를 스캔하기 전에 변경된 영역에 가장 가까운 문서를 우선합니다.
• 신호 기준 또는 출력 형태가 필요할 때 references/heuristics.md를 읽습니다.

4. 결과 분류

• low: 문서가 대체로 괜찮거나, 약한 신호만 있고 오래된 참조가 발견되지 않음.
• medium: 드리프트 가능성이 있거나, 공개 표면 변경이 강하지만 오래된 문서가 확인되지 않음.
• high: 특정 오래된 용어, 경로 또는 누락된 지침이 있는 드리프트가 확인되었거나 가능성이 높음.

5. 출력을 간결하게 유지

다음 형태를 사용합니다:

1. 위험 수준
2. 이유
3. 영향을 받는 문서 파일
4. 권장 편집 사항

규칙

• 의미론적 추측보다 diff의 결정적 증거를 선호합니다.
• 구체적인 오래된 참조, 누락된 문서 업데이트 또는 이름이 변경된 경로를 지목할 수 없으면 확인된 드리프트라고 주장하지 마십시오.
• 증거가 불완전하면 확실성을 과장하지 말고 possible drift라고 말합니다.
• 사용자 동작을 변경하지 않는 한 서식 전용, 주석 전용 및 테스트 전용 변경 사항은 무시합니다.
• 결과를 짧고 실행 가능하게 유지합니다.