issueops-sync-issue
Refresh the body of an issue or provider-native child this cycle already published, with drift classification, managed-section preservation, a fail-closed body compare-and-swap, and explicit good and
SKILL.mdskills/issueops-sync-issue/SKILL.md
GitHubIssueOps Sync Issue
이 스킬의 일은 이미 만든 Issue의 본문을 지금 사이클에 맞게 다시 쓰는 것이다. 새 Issue를 만들거나, 계획을 세우거나, 구현하지 않는다.
- 새 Issue·child 생성:
issueops-create-issue - PR/MR 본문 최신화:
issueops-sync-pr - 전체 흐름:
issueops - 원격 쓰기 절차:
issueops-remote-write - provider 세부 규칙:
remote-issue.md
시작 전 issueops next --id "$ISSUEOPS_ID" --json으로 현재 단계를
확인한다. 본문 동기화는 어느 단계에서든 할 수 있지만, next가 가리키는 단계의 일을
미루는 대신 하는 것이 아니다.
언제 쓰는가
Issue 본문은 만든 시점에 멈춰 있고 사이클은 계속 움직인다. 다음 중 하나가 사실이면 본문이 낡은 것이다.
| 신호 | 본문에서 낡은 부분 |
|---|---|
| child를 새로 만들었거나 닫았다 | ## 하위 Task의 URL·wave·prerequisite |
| 범위를 좁히거나 넓혔다 | ## 구현 범위, ## 비목표 |
| 완료 기준이 바뀌었다 | ## 완료 기준 checklist |
| 검증 명령이 바뀌었다 | ## 검증 |
| devil's-advocate·호환성 검토로 방향이 바뀌었다 | ## 위험과 트레이드오프 |
낡았다는 판정을 나이로만 하지 않는다. sync-issue preview가 돌려주는
drift가 판정의 기준이고, age_days는 참고 값이다.
흐름
flowchart LR
a["cycle·provider 확인"] --> b["preview로 drift 확인"]
b --> c{"drift"}
c -->|in_sync| d["쓰지 않고 종료"]
c -->|remote_edited| e["사람 편집을 새 본문에 반영"]
c -->|stale| f["본문 재작성"]
e --> f
f --> g["fluent-korean 다듬기"]
g --> h["같은 sha로 confirm"]
h --> i["readback·기록 확인"]
시작 게이트
ISSUEOPS_ID와issueops list --repo "$PWD" --json으로 cycle을 찾는다. 찾은 record가 상태의 기준이다.- record에 canonical
issue_url이 있어야 한다. 없으면 이 스킬이 아니라issueops-create-issue가 할 일이다. - 원격 본문을 읽기 전에 새 본문을 확정하지 않는다. preview가 현재 원격 본문을 알려주고, 그 위에서 다시 쓴다.
- child를 대상으로 하려면 그 URL이 현재 parent의 provider-native child여야 한다. 하네스가 hierarchy를 검증한 뒤에만 쓴다.
- 관리 블록(
issueops:completion,issueops:devils-advocate,issueops:issue-create)은 body-file에 넣지 않는다. 하네스가 원격에서 그대로 떼어내 다시 붙인다. 넣으면 명령이 거부한다.
drift를 읽는 법
preview는 --confirm 없이 실행하며 provider를 변경하지 않는다.
issueops remote sync-issue \
--id "$ISSUEOPS_ID" --body-file "$BODY_FILE" --json
drift |
뜻 | 다음 행동 |
|---|---|---|
in_sync |
제안 본문이 원격과 같다 | 쓰지 않는다. 최신화할 것이 없다 |
stale |
원격은 하네스가 마지막에 쓴 그대로고, 제안이 앞선다 | 그대로 confirm |
remote_edited |
원격 본문이 하네스 기록과 다르다 | 사람이 손댄 것이다. 아래 절차 |
expected_body_sha256은 confirm에 그대로 넘길 값이고, preserved_sections는
하네스가 보존할 관리 블록 목록이다.
사람이 수정한 본문
drift가 remote_edited면 누군가 원격에서 직접 고쳤다는 뜻이다. 그 편집을
지우고 덮어쓰지 않는다.
- 원격 본문을 열어 사람이 추가·수정한 문단을 확인한다.
- 그 내용을 새 본문에 반영한다. 남길 가치가 없다고 판단했다면 왜 빼는지 사이클 기록에 남긴다.
--accept-remote-edits를 붙여 그 편집을 확인했음을 명시한다. 이 플래그 없이는 confirm이 거부된다.
읽기 좋은 body
본문 형식은 issueops remote render-template 골격과
references/readable-body.md를
그대로 따른다. 최신화라고 해서 낡은 문장을 남겨 두고 새 문단만 덧붙이지 않는다.
본문은 통째로 교체되므로, 지금 사실이 아닌 문장은 지운다. 옛 형식(## 문제로
시작하는 본문)을 동기화할 때는 새 계약의 절로 다시 쓴다.
원격에 쓰기 전에 fluent-korean 스킬을 Skill 도구로 호출해서 문장을 다듬는다.
가독성 검사는 문장이 자연스러운지 판정하지 않으므로 번역투와 AI 티는 걸러지지
않는다. 이 호출을 건너뛴 body로는 --confirm을 붙이지 않는다.
가독성 판정 읽기
preview 응답에는 판정이 두 개 있다.
| 필드 | 대상 | 쓰는 법 |
|---|---|---|
readability |
제안 본문 | critical이 있으면 confirm이 거부된다. 고친 뒤 preview부터 다시 한다. warning은 고치거나 남기는 이유를 적는다 |
live_readability |
원격의 현재 본문 | warning만 담는다. 여기 나온 요약 누락·해시·하네스 용어가 새 본문에서 사라졌는지 확인한다 |
--template을 생략하면 제안 본문의 절 제목으로 템플릿을 추론한다(## 재현 절차 →
bug, ## 제안 → proposal, --url child → child_task, 그 밖 → implementation_task).
추론이 의도와 다르면 --template을 넘긴다.
나쁜 예
| 나쁜 입력 | 왜 나쁜가 | 고치는 방법 |
|---|---|---|
| 새 문단만 아래에 덧붙임 | 본문은 통째로 교체된다. 낡은 문장이 그대로 남는다 | 낡은 문단을 지우고 다시 쓴다 |
| body-file에 완료 기록 블록 포함 | 관리 블록은 하네스가 소유한다 | 빼고 하네스가 재부착하게 둔다 |
preview 없이 --confirm |
--expected-body-sha256이 없어 거부된다 |
preview부터 실행한다 |
remote_edited에 --accept-remote-edits만 붙임 |
사람 편집을 확인하지 않고 지운다 | 편집 내용을 새 본문에 반영한 뒤 붙인다 |
parent record 없이 임의 --url |
다른 이슈를 덮어쓸 수 있다 | 현재 parent의 child만 대상으로 한다 |
gh issue edit / glab api PUT 직접 실행 |
IssueOps readback과 기록을 우회한다 | remote sync-issue를 쓴다 |
Canonical sync
preview → 본문 재작성 → 같은 sha로 confirm 순서를 지킨다.
issueops remote sync-issue \
--id "$ISSUEOPS_ID" --provider "$PROVIDER" \
--template implementation_task --body-file "$BODY_FILE" --json
preview가 돌려준 expected_body_sha256을 그대로 넘겨 확정한다.
issueops remote sync-issue \
--id "$ISSUEOPS_ID" --provider "$PROVIDER" \
--body-file "$BODY_FILE" \
--expected-body-sha256 "$EXPECTED_BODY_SHA256" \
--host "$HOST" --session-id "$SESSION_ID" --cwd "$WORKER_PATH" \
--confirm --json
provider-native child는 --url로 지정한다. hierarchy 검증을 통과한 URL만 쓴다.
issueops remote sync-issue \
--id "$ISSUEOPS_ID" --url "$CHILD_URL" \
--body-file "$CHILD_BODY_FILE" \
--expected-body-sha256 "$EXPECTED_BODY_SHA256" \
--host "$HOST" --session-id "$SESSION_ID" --cwd "$WORKER_PATH" \
--confirm --json
confirm 결과의 updated, remote_body_sha256, preserved_sections를 확인하고,
관리 블록이 원격 본문에 남아 있는지 readback으로 본다. sha가 어긋나면 원격이
그 사이에 바뀐 것이므로 재실행하지 말고 preview부터 다시 한다.
품질·성능 게이트
- 품질: drift 판정 기록, 관리 블록 보존,
readability.critical0과 warning 처리, 원격 write 전fluent-korean호출, compare-and-swap sha 일치, child hierarchy 검증, secret redaction, readback. - 성능: 최신화 단계에서만 이 스킬을 로드한다. 생성 스킬과 PR reference를 함께 중복 로드하지 않는다.
- 검증:
python3 scripts/validate-skill.py skills/issueops-sync-issue
python3 scripts/verify-skill-shell.py skills/issueops-sync-issue
wc -c skills/issueops-sync-issue/SKILL.md
provider, 대상 URL, 사람 편집 반영 여부, body 완성도, 또는 관리 블록 보존이 모호하면 쓰지 않는다.