중복 PR/이슈 태깅

중복 PR 및 이슈 태깅

유지보수자가 풀 리퀘스트나 이슈가 기존 작업의 중복인지 판단해야 할 때 이 스킬을 사용하세요.

이 스킬은 유지보수자의 트라이지(triage) 및 그룹화를 위한 것입니다. PR의 구현 품질을 검토하는 용도가 아닙니다.

필수 설정

이 설정이 완료될 때까지 중복 그룹이나 주석을 작성하지 마십시오. gitcrawl과 실시간 gh를 사용한 읽기 전용 발견은 계속 진행할 수 있습니다.

보조 스킬

로컬 후보 발견을 위해 먼저 $gitcrawl을 사용하세요. prtags 저장소의 skills/prtags/SKILL.md에 있는 prtags 스킬을 사용 가능할 때 사용하세요.

CLI 설치

아래 고정된 릴리스에서 prtags를 설치하세요. 유지보수자가 출시되지 않은 동작을 테스트하려는 경우가 아니라면 예전 로컬 빌드에 의존하지 마십시오.

prtags CLI 설치 경로:

GOBIN="$HOME/.local/bin" go install github.com/dutifuldev/prtags/cmd/[email protected]

prtags는 OpenClaw 조직 외부에 있으므로, 이 설치는 Go 모듈 프록시가 해석하고 공개 체크섬 데이터베이스가 검증한 검토된 버전에 고정됩니다. GOBIN은 설치된 실행 파일을 이전 설치 프로그램과 같은 사용자 로컬 디렉터리에 유지하므로, 기존 $HOME/.local/bin PATH가 새로 설치된 버전을 계속 해석할 수 있습니다. 원격 스크립트를 셸로 파이핑하여 설치하지 말고, 설치를 브랜치로 지정하지 마십시오. 둘 중 하나라도 실행 시 해당 타사가 제공하는 모든 것을 유지보수자의 권한으로 실행하게 됩니다. 최신 prtags 릴리스로 이동하는 것은 이 파일의 검토된 변경 사항이지, 작업 중간 단계가 아닙니다.

prtags 인증

prtags는 OAuth 장치 흐름을 통해 유지보수자의 자체 GitHub 계정으로 로그인해야 합니다. 대화형 트라이지를 위해 공유 유지보수자 토큰을 사용하지 마십시오.

prtags auth login
prtags auth status

예상 결과는 prtags가 로그인된 유지보수자 ID를 로컬에 저장하고 해당 계정을 인증된 쓰기에 사용하는 것입니다.

설정 누락 규칙

워크플로우를 시작하기 전에 사전 점검을 요구하지 마십시오. 실제로 도구나 계정 상태가 필요할 때까지 일반 단계를 진행하십시오.

쓰기 단계에서 prtags가 없거나 로그인되지 않았음을 발견하는 즉시 즉시 중단하십시오. 그 시점 이후 부분 쓰기 모드로 계속하지 마십시오.

prtags가 없으면 사용자에게 CLI 설치의 고정된 설치 명령어를 실행하도록 요청하십시오. 해당 섹션을 설치된 버전의 단일 출처로 유지하십시오. 다른 설치 경로를 즉흥적으로 만들지 마십시오.

prtags auth status에서 사용자가 로그인되지 않았음을 보여주면 사용자에게 다음을 실행하도록 요청하십시오:

prtags auth login

누락된 도구나 로그인 상태가 수정된 후에만 재개하십시오.

읽기 경로 기본값

이 워크플로우에서 후보 발견을 위해 gitcrawl을 먼저 사용하십시오. 관련 이슈, 중복 시도, 종료된 스레드의 로컬 기록 및 클러스터링 계층으로 취급하십시오.

대상 스레드와 조치 가능한 판단을 내리기 전의 모든 후보에 대해 실시간 gh 또는 gh api를 사용하십시오. gitcrawl이 구체적인 이유로 누락되거나 오래된 경우 실시간 GitHub를 사용하십시오. 예:

• 대상 또는 후보가 아직 존재하지 않음
• 로컬 데이터가 필요한 결정에 명백히 오래되었거나 불완전함
• gitcrawl이 오류가 발생하거나 시간 초과되거나 필요한 이웃/검색 데이터가 없음

실시간 GitHub 검색으로 대체할 때는 그렇게 했다는 사실과 이유를 기록하십시오.

이후 prtags 대상 수준 쓰기가 자체 미러가 따라잡지 못해 실패하면, 강제 대체 쓰기 경로 대신 중단하고 치료 백엔드에 대상 객체가 없다고 보고하십시오.

목표

각 대상 PR 또는 이슈에 대해:

1. 중복 증거 수집
2. 실제 중복인지 결정
3. 해당 중복 클러스터에 대해 하나의 prtags 그룹 생성 또는 재사용
4. 유지보수자 판단을 prtags에 저장
5. 해당 통합이 구성된 경우 일반 prtags 그룹 쓰기에 의존하여 GitHub 댓글 동기화 유도

도구 역할

도구를 다음 경계와 함께 사용하십시오:

• gitcrawl은 후보 생성 및 기록 컨텍스트
  • 로컬 제목/본문 검색, 이웃, 클러스터 및 종료된 스레드 발견을 위해 먼저 사용
  • 실시간 GitHub가 확인할 때까지 모든 후보를 리드로 처리
• gh는 실시간 GitHub 진실
  • 대상 상태, 본문, 댓글, 리뷰, 파일, 연결된 이슈 및 현재 열림/닫힘/병합 상태에 사용
  • gitcrawl이 오래되었거나 데이터가 누락되거나 필요한 쿼리를 표현할 수 없는 경우에만 gh search 사용
• prtags는 유지보수자 치료 계층
  • 중복 그룹을 생성하거나 재사용하는 데 사용
  • 중복 상태, 신뢰도, 근거 및 그룹 요약을 저장하는 데 사용
  • GitHub 대상 그룹 댓글의 진실 소스로 사용

작업 규칙

• 제목만 비슷하다고 해서 중복이라고 부르지 마십시오.
• 동일한 파일이 변경되었다고 해서 중복이라고 부르지 마십시오.
• 중복 클러스터는 동일한 사용자 직면 문제, 동일한 의도 및 상당히 중복되는 구현 또는 조사 컨텍스트를 기반으로 해야 합니다.

하나의 그룹 규칙

중복 그룹을 배타적으로 취급하십시오. PR 또는 이슈는 한 번에 최대 하나의 중복 그룹에 속해야 합니다.

즉:

• 새 그룹을 만들기 전에 동일한 중복 스토리를 이미 나타내는 기존 그룹을 검색하십시오.
• 대상이 이미 다른 중복 그룹에 속하는 것으로 보이면 중단하고 먼저 해당 충돌을 해결하십시오.
• 표현이 약간 다르다고 해서 동일한 대상에 대해 두 번째 그룹을 만들지 마십시오.
• 두 개의 그럴듯한 기존 그룹이 겹치고 판단을 안전하게 병합할 수 없으면 중단하고 유지보수자에게 문의하십시오.

이 규칙은 속도보다 중요합니다. 스킬은 문제당 하나의 일관된 중복 클러스터를 유지해야 하며, 여러 개의 거의 중복된 클러스터가 있어서는 안 됩니다.

좋은 중복 그룹이 나타내는 것

중복 그룹은 기본 문제와 의도된 수정 방향을 설명해야 합니다. 키워드만 공유한다고 항목을 그룹화하지 마십시오.

좋은 그룹 형태:

• 동일한 사용자 직면 버그 또는 동일한 유지보수자 직면 작업
• 동일한 하위 시스템 또는 코드 표면
• 동일한 의도된 변경 방향
• 동일한 가능한 중복 해결 경로

나쁜 그룹 형태:

• "Slack을 건드리는 모든 PR"
• "재시도를 언급하는 모든 이슈"
• "인증 관련 모든 항목"

그룹 제목은 실제 문제의 이름을 지정해야 합니다. 그룹 설명은 의도와 코드 표면을 요약해야 합니다.

예시:

• gateway: 채널 상태 부트스트랩의 시작 회귀
• whatsapp: QR 사전 점검 시간 초과 처리
• release: 교차 OS 검증 핸드오프 격차

증거 체크리스트

중복을 선언하기 전에 최소 두 가지 범주에서 증거를 수집하십시오. gitcrawl 이웃, 검색 결과 및 클러스터 멤버십은 후보 생성으로 간주되며, 그 자체로 충분한 증거가 아닙니다.

PR의 경우:

• 동일하거나 거의 동일한 문제 설명
• 동일한 변경 파일 또는 겹치는 파일 범위
• 동일한 수정 방향
• 동일한 하위 시스템 및 실패 모드
• 동일한 연결된 이슈 또는 동일한 사용자 가시 증상

이슈의 경우:

• 동일한 사용자 직면 문제
• 동일한 재현 스토리 또는 동일한 실패 모드
• 동일한 가능한 수정 영역
• 동일한 PR이 이미 연결되었거나 논의됨
• 동일한 유지보수자가 이미 동일한 중복 그룹화로 유도함

표현 유사성만 있다면 충분하지 않습니다.

1단계: 대상 읽기

대상 자체를 읽는 것으로 시작하십시오. 현재 대상 상태에 실시간 GitHub를 사용하십시오.

PR의 경우:

gh pr view <번호> --json number,title,state,mergedAt,body,closingIssuesReferences,files,comments,reviews,statusCheckRollup

이슈의 경우:

gh issue view <번호> --json number,title,state,body,comments,closedAt

기록:

• 대상 유형 및 번호
• 제목
• 문제 설명
• 제안된 의도
• 하위 시스템
• 열림, 닫힘 또는 병합 여부
• 이미 인간이 언급한 가능한 중복 스레드가 있는지 여부

2단계: Gitcrawl로 광범위하게 검색

gitcrawl을 먼저 사용하십시오. 로컬 OpenClaw 기록 및 클러스터링 소스이기 때문입니다. gitcrawl에 데이터가 없거나, 오래되었거나, 실패하지 않는 한 광범위한 실시간 GitHub 검색으로 전환하지 마십시오.

대상과 가까운 스레드부터 시작하십시오:

gitcrawl threads openclaw/openclaw --numbers <이슈-또는-pr-번호> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <이슈-또는-pr-번호> --limit 20 --json

그런 다음 주요 구문과 하위 시스템 용어를 검색하십시오:

gitcrawl search openclaw/openclaw --query "<제목 또는 본문의 주요 구문>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<하위 시스템 또는 오류 구문>" --mode hybrid --limit 20 --json

가능한 클러스터를 검사하십시오:

gitcrawl cluster-detail openclaw/openclaw --id <클러스터-id> --member-limit 20 --body-chars 280 --json

PR의 경우, 실시간 파일 데이터로 가능한 코드 중복을 확인하십시오:

gh pr view <후보-pr> --json number,title,state,mergedAt,files,body,comments,reviews

이슈의 경우, 실시간으로 가능한 중복 이슈 상태와 댓글을 확인하십시오:

gh issue view <후보-이슈> --json number,title,state,body,comments,closedAt

3단계: 격차를 위해 실시간 GitHub 검색 사용

다음과 같은 경우 gitcrawl 이후 대상 실시간 GitHub 검색을 사용하십시오:

• 대상이 로컬 저장소에 비해 너무 새로운 경우
• 댓글이나 리뷰가 중요하고 로컬 저장소에 없는 경우
• 정확한 구문이 로컬 결과에 나타나지 않았지만 이슈/PR이 GitHub가 알아야 할 만큼 충분히 최신인 경우

gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "<주요 구문>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<주요 구문>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<오류 또는 유지보수자 구문>"

4단계: 결과 결정

다음 결과 중 하나를 선택하십시오:

• not_duplicate
• duplicate_needs_judgment
• duplicate_confirmed

증거가 유지보수자가 중복 항목을 안전하게 닫거나 다시 태그할 수 있을 만큼 강력한 경우에만 duplicate_confirmed를 사용하십시오.

다음과 같은 경우 duplicate_needs_judgment를 사용하십시오:

• 문제는 같아 보이지만 구현 목표가 다른 경우
• 코드 중복이 약한 경우
• 이슈 표현이 모호한 경우
• 두 가지 유효한 중복 그룹 해석이 있을 수 있는 경우
• 대상이 두 개의 기존 중복 그룹과 교차하는 것으로 보이는 경우

5단계: 하나의 prtags 그룹 재사용 또는 생성

그룹을 만들기 전에 prtags에서 기존 그룹을 검색하십시오.

그룹에 대한 텍스트 검색부터 시작하십시오:

prtags search text -R openclaw/openclaw "<문제 구문>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<문제 요약>" --types group --limit 10
prtags group list -R openclaw/openclaw

가능한 그룹을 검사하십시오:

prtags group get <그룹-id>
prtags group get <그룹-id> --include-metadata

다음과 같은 경우 기존 그룹을 재사용하십시오:

• 동일한 문제를 나타내는 경우
• 이미 명확히 관련된 멤버를 포함하는 경우
• 대상을 추가해도 그룹이 일관되게 유지되는 경우

gitcrawl이 여러 PR 또는 이슈를 서로 가까이 배치했다고 해서 기존 그룹을 확장하지 마십시오. 새 멤버를 추가하기 전에 실제 구현 경로와 유지보수자 의도가 여전히 일치하는지 확인하십시오.

기존 그룹이 명확히 맞지 않는 경우에만 새 그룹을 만드십시오.

문제 기반 제목과 의도 기반 설명으로 그룹을 만드십시오:

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<문제 중심 제목>" \
  --description "<동일한 의도, 하위 시스템 및 중복 해결 경로>" \
  --status open

그런 다음 대상과 알려진 중복 멤버를 첨부하십시오:

prtags group add-pr <그룹-id> <pr-번호>
prtags group add-issue <그룹-id> <이슈-번호>

대상이 이미 다른 중복 그룹에 속하는 것으로 보이고 해당 그룹을 안전하게 재사용할 수 없으면 중단하십시오. 두 번째 그룹을 만들지 마십시오.

6단계: 주석 필드가 있는지 확인

field ensure를 사용하여 스킬이 멱등성을 가지도록 하십시오.

권장 대상 수준 필드:

prtags field ensure -R openclaw/openclaw --name duplicate_status --scope pull_request --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_status --scope issue --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope pull_request --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope issue --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope pull_request --type text --searchable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope issue --type text --searchable

권장 그룹 수준 필드:

prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope group --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope group --type text --searchable
prtags field ensure -R openclaw/openclaw --name cluster_summary --scope group --type text --searchable

7단계: 유지보수자 판단을 prtags에 저장

PR의 경우:

prtags annotation pr set -R openclaw/openclaw <pr-번호> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<동일한 문제, 동일한 수정 방향, 겹치는 파일 및 댓글>"

이슈의 경우:

prtags annotation issue set -R openclaw/openclaw <이슈-번호> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<동일한 사용자 직면 문제 및 동일한 의도된 수정 경로>"

그룹의 경우:

prtags annotation group set <그룹-id> \
  duplicate_confidence=high \
  cluster_summary="<한 문장 문제 요약>" \
  duplicate_rationale="<이 항목들이 하나의 중복 클러스터에 속하는 이유>"

증거가 불완전한 경우 duplicate_status=candidate로 설정하고 신뢰도를 낮추십시오.

PR 또는 이슈별 주석 쓰기가 prtags가 대상을 해결할 수 없어 실패하면 강제 대체 쓰기 경로를 사용하지 마십시오. 작성할 수 있었던 그룹 상태를 유지하고, 치료 백엔드가 여전히 대상 객체를 찾을 수 없다고 보고하고, 작업을 연기하십시오.