gitea-agent/harness/agents/spec/skills/gitea-discovery-review/SKILL.md

---
name: gitea-discovery-review
description: 수정된 Gitea Discovery를 검토하고 정규화한다.
version: 0.3.0
author: genichin, Hermes Agent
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [gitea, discovery, review, specification]
    related_skills: [gitea-discovery-authoring, gitea-repository-cache-bootstrap]
---

# Gitea Discovery Review

사용자가 Gitea Issue의 Discovery body에서 OQ를 선택하거나 본문을 수정한 뒤 그 수정본을 검토해 달라고 요청할 때 사용한다. 현재 Issue body를 review candidate의 정본으로 삼아 결정 전파, 모순 제거, 후속 OQ와 문서 영향 재평가를 수행한다. Discovery 승인, label·assignee 변경, 구현 handoff 또는 후속 문서·source 작성은 수행하지 않는다.

Gitea 인증과 readback은 [Gitea authenticated access 운영 지침](../../../../operations/gitea-access.md), 작성 규칙은 [Discovery 작성 방법](../../../../docs/discovery/README.md), visible 구조는 [Discovery 템플릿](../../../../docs/discovery/TEMPLATE.md), cache와 lock 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md)만 정본으로 사용한다.

## 사용 시점

다음과 같이 exact repository와 Issue의 수정된 Discovery 검토를 요청받았을 때 사용한다.

```text
<owner>/<repository> 이슈 #<number>의 수정된 discovery를 검토하라
```

이 요청은 실제 정규화가 필요할 때 Issue body만 교체하는 것을 승인한다. 검토 전 candidate를 comment로 보존하지 않으며 comment, title, state, label, assignee, milestone, repository file 또는 source write는 승인하지 않는다. 최초 Discovery 작성에는 `gitea-discovery-authoring`을 사용한다.

## 입력 승인 gate

- body 첫 줄이 exact `<!-- gitea-agent:discovery-draft/v2 -->`이고 TEMPLATE의 H2 순서가 정확해야 한다.
- 최초 Discovery authoring의 원본 provenance comment는 authoring 계약에 맞는 exact comment 하나여야 하며 review는 이를 읽기만 한다.
- OQ ID는 고유하고 증가해야 하며 각 선택지는 checkbox여야 한다.
- OQ마다 선택된 항목이 0개 또는 1개여야 한다. 2개 이상이면 사용자의 결정을 추측하지 않고 외부 write 없이 중단한다.
- credential, token, password 또는 secret의 실제 값이 body에 포함된 것으로 의심되면 comment를 포함한 어떤 외부 write도 수행하지 않는다.
- malformed marker·섹션·comment·OQ 또는 identity가 불명확하면 자동 복구하지 않는다.

## OQ 검토 규칙

- 선택이 0개인 OQ는 미해결 상태로 유지한다.
- 선택이 정확히 1개인 OQ는 선택지의 의미를 확대하지 않고 사용자 결정으로 채택한다. 사용자 선택을 기술적 전제가 성립한다는 증거로 취급하지 않는다.
- 채택한 결정은 `확정된 결정`에 반영하고 필요한 `포함 범위`, `제외 범위`, `제약 조건`, `저장소 근거`, `문서 영향 및 산출물`에 일관되게 전파한다. 핵심 기술적 전제를 확인하지 못하면 선택과 미검증 이유를 해당 OQ에 남기고 제거하지 않는다. 전파와 필요한 전제 확인이 끝난 OQ만 제거한다.
- 선택된 결정이 기존 결정·범위·저장소 근거와 충돌하면 임의로 우선순위를 정하지 않는다. 충돌을 해소할 수 있는 새 OQ를 열거나, 선택지만으로 안전한 질문을 구성할 수 없으면 외부 write 없이 중단한다.
- 사용자 prose 수정은 현재 문서 전체와 pinned source revision을 기준으로 검토한다. 이전 local artifact는 진단에만 사용할 수 있고 authoritative baseline으로 간주하지 않는다.
- 검토 과정에서 새 사용자 결정이 필요하면 기존 최대 OQ 번호의 다음 ID를 사용한다. 삭제된 ID를 재사용하지 않으며 모든 선택지는 미선택 checkbox로 두고 추천안을 하나만 표시한다.
- 미해결 OQ가 없으면 `## 미해결 질문`의 본문을 exact `없음`으로 쓴다.
- 추천안을 사용자가 선택한 결정처럼 기록하거나 사용자 대신 checkbox를 선택하지 않는다.

## 절차

1. 요청에서 exact `owner`, `repository`, Issue 번호를 추출하고 단일 안전 경로 요소인지 검증한다. `operations/repository-cache.md`를 새로 읽고 canonical cache 경로를 계산·검증한다.
2. Authenticated Gitea API adapter로 review role의 stable account identity를 확인한다. 대상 cache가 없으면 `gitea-repository-cache-bootstrap`을 완료하고 bootstrap·repository lock이 모두 해제됐는지 확인한다. 기존 cache는 자동 초기화하지 않는다. Cache와 lock 경로의 안전성을 검증한 뒤 canonical Issue lock을 획득한다.
3. exact Issue와 전체 comments를 읽어 body, `updated_at`, title, state, labels, assignees, milestone과 comment baseline을 immutable snapshot으로 보존한다.
4. 이 스킬의 입력 승인 gate로 current body와 최초 authoring의 원본 provenance comment를 검증한다. 실패하면 comment와 body를 쓰지 않는다.
5. Issue lock을 유지한 채 canonical 지침에 따라 기존 cache를 검증한다. 검증에 실패하면 자동 초기화하거나 복구하지 않고 중단한다.
6. repository lock을 canonical 순서로 획득해 origin을 fetch하고 Gitea default-branch SHA와 local ref가 정확히 일치하는 revision을 pin한다.
7. pinned SHA에서 current Discovery의 모든 저장소 근거, 다섯 후속 문서 경로, 요구사항 ID·파일명과 사용자 prose 수정의 사실성을 조사한다. 움직이는 branch나 다른 workspace를 근거로 사용하지 않는다.
8. 각 OQ의 선택 수를 판정한다. 선택된 결정이 특정 API·dependency·runtime·배포 기능에 의존하면 pinned 저장소와 적용 버전의 공식 문서·소스를 조사해 지원 여부와 구현 경로를 확인한다. 조사만으로 판단할 수 없고 실행 실험이 필요하면 기술적 전제 검증을 미완료로 남긴다. 선택된 결정을 관련 모든 섹션에 전파하고, 새 모순·누락으로 새 사용자 결정이 필요할 때만 OQ 검토 규칙에 따라 새 OQ를 추가한다.
9. `문서 영향 및 산출물`을 README 정책에 따라 전부 다시 판정한다. 요구사항명세서의 exact ID·경로·제목·포함할 내용·제외할 내용과 다른 문서의 구체적 변경 계약을 현재 결정과 pinned SHA에 맞춘다.
10. 조사 종료 시 Gitea default-branch SHA와 local ref가 pinned SHA와 여전히 일치하는지 확인하고 repository lock을 해제한다. Issue lock은 유지한다.
11. trusted workflow directory에 revised body artifact를 만들고 marker, H2 순서, placeholder 부재, OQ ID·checkbox, 결정 전파, 문서 영향, repository evidence와 credential 부재를 검증한다.
12. revised body가 current body와 exact-match하면 comment와 body write 없이 no-op으로 종료한다.
13. write 직전에 Issue와 comments를 다시 읽는다. snapshot의 body·`updated_at` 또는 comment baseline이 drift했으면 외부 write 없이 중단한다.
14. snapshot의 body·`updated_at`·comment baseline과 비본문 필드가 불변일 때 revised body artifact의 exact bytes로 Issue body 하나만 교체한다. title, state, labels, assignees, milestone은 write payload에 포함하지 않는다.
15. Issue와 comments를 다시 읽어 body exact-match, 비본문 필드 불변성과 comment baseline 완전 불변을 검증한다. review는 어떤 comment도 추가·수정·삭제해서는 안 된다.
16. 동일 pinned source revision과 readback한 현재 본문을 기준으로 내용 검토·정규화를 다시 적용해 결과가 현재 본문과 exact-match인지 확인한다. Replay에서는 외부 write를 수행하지 않으며, 불일치하면 replay 검증 실패로 보고한다. 확인 후 Issue lock을 해제한다.

## 금지 사항

- 사용자의 미선택 OQ를 자동으로 선택하지 않는다.
- 선택된 결정을 근거 없이 확장하거나 다른 OQ의 답으로 간주하지 않는다.
- review 중 Issue를 승인하거나 구현 상태로 전환하지 않는다.
- 검토 전 body 또는 revised body를 comment로 보존하지 않고 어떤 comment도 추가·수정·삭제하지 않는다.
- label, assignee, title, state, milestone 또는 최초 authoring의 원본 provenance comment를 변경하지 않는다.
- 요구사항명세서, data-model, interface-contract, project-structure, runtime-flow 또는 source를 직접 작성하지 않는다.
- stale cache, unpinned source, 다른 workspace, installed package 또는 이전 local artifact를 authoritative 근거로 사용하지 않는다.
- 불확실한 Gitea write를 blind retry하지 않는다.

## 검증 및 보고

완료 전에 다음을 구분해 보고한다.

- authenticated Gitea identity와 exact target
- Issue/comment pre-write snapshot과 입력 승인 gate 결과
- cache 경로, bare·remote 검증, fetch와 pinned Gitea/local SHA
- 사용자 선택 OQ, 유지한 OQ, 제거한 OQ와 새로 연 OQ 및 기술적 전제 검증 결과·근거·미검증 항목
- 사용자 prose 수정의 수용·조정·거부 결과와 근거
- 확정된 결정의 섹션별 전파 결과
- 다섯 후속 문서의 조치·exact 경로·변경 내용 검증 결과
- revised body exact readback과 비본문 필드 불변성
- comment baseline 완전 불변과 내용 검토·정규화 재적용 결과의 exact-match 여부; 추가 조회의 불변 확인만으로 replay no-op 검증 완료를 보고하지 않는다.
- partial 또는 fail-closed 상태

프로세스 exit나 API write 응답만으로 성공을 주장하지 않는다. Authoritative readback 또는 replay 검증이 하나라도 실패하면 completed로 보고하지 않는다.