---
name: validate-agent-ui
description: agent-ui scaffold, definition/frame/component/wireframe/source evidence/status 정합성을 맞추고 필요한 USER_REVIEW와 code sync intent를 분리하는 스킬
---

# validate-agent-ui

## 목적

`agent-ui/` 구조와 문서 그래프 정합성을 검사하고 자동 보정한다.
definition, component, frame, visual source, USER_REVIEW, archive가 서로 뒤처진 상태를 같은 수준으로 맞추며, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다.

## 언제 호출할지

- agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때
- view/component/frame 문서가 서로 어긋났는지 확인할 때
- view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때
- Excalidraw visual source와 frame index 연결을 검사할 때
- agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때
- 수동 호출에서 정합성 통과 후 code sync가 필요한지 판단할 때
- 사용자가 "화면정의서와 코드가 안 맞아"처럼 UI 정의와 코드 결과물의 불일치를 보고할 때

## 입력

- `scope`: `all`, `internal`, `implementation`, `view:<view-id>`, `component:<component-id>`, `frame:<view-id>` 중 하나. 기본값은 `all` (선택)
- `repair`: `true` 또는 `false`. 기본값은 `true` (선택)
- `sync-intent`: `auto`, `required`, `skip`, `inherited` 중 하나. 기본값은 수동 호출에서 `auto`, `update-agent-ui` 후속 호출에서 `inherited` (선택)
- `sync-mode`: `incremental` 또는 `full`. 기본값은 `incremental` (선택)

## 먼저 확인할 것

- [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다.
- [ ] `agent-ui/` 존재 여부를 확인한다. 없으면 `create-agent-ui` 대상이라고 보고하고 중단한다.
- [ ] `agent-ui/definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md` 존재 여부를 확인한다.
- [ ] scope에 해당하는 활성 definition/frame 문서만 읽는다.
- [ ] `scope=view:<view-id>` 또는 `scope=component:<component-id>`이면 해당 문서의 Source Evidence code path를 확인한다.
- [ ] `scope=all`, `scope=implementation` 또는 sync intent가 있으면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다.
- [ ] `agent-ui/.sync-state.json`이 있으면 읽고, 없으면 sync 기준 없음으로 보고한다.
- [ ] archive는 경로와 tree 대응만 확인하고, 사용자가 과거 내용 확인을 요청하지 않았으면 본문을 읽지 않는다.
- [ ] 필요한 템플릿만 `agent-ops/skills/common/_templates/agent-ui/`에서 읽는다.

## 실행 절차

1. **인벤토리 작성**
   - `definition/views/**/index.md`에서 view 목록을 만든다.
   - `definition/components/**/index.md`에서 component 목록을 만든다.
   - `frame/views/**/index.md`에서 frame 목록을 만든다. frame이 없는 view는 visual source가 없는 정상 상태로 본다.
   - 활성 Markdown 문서의 frontmatter에서 `ui_doc_type`과 문서 유형별 필드를 수집한다.
     - view: `view_id`, `status`, `frame`, `source_evidence`, `regions`
     - component: `component_id`, `status`, `source_evidence`
     - frame-view: `view_id`, `definition`, `visual_source`, `regions`
     - definition-index: `surface_type`, `source_evidence`
   - 같은 레벨의 `<name>.md`와 `<name>/` 혼재 여부를 확인한다.

2. **구조 검증과 자동 보정**
   - 필수 루트 문서가 없고 `repair=true`이면 템플릿으로 생성한다.
   - view/component 디렉터리에 `index.md`가 없고 의도가 명확하면 템플릿으로 생성한다.
   - frame 디렉터리는 visual source가 있을 때만 `index.md` 생성 대상으로 삼는다.
   - `.excalidraw` 파일이 하나 있고 frame index의 visual source가 비어 있으면 해당 파일을 등록한다.
   - archive/user-review 디렉터리가 없고 필요하면 생성한다.
   - `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다.

3. **definition 정합성 검사**
   - 활성 Markdown 문서에 `ui_doc_type` frontmatter가 있는지 확인한다.
   - `ui_doc_type`이 경로와 맞는지 확인한다. 예: `definition/views/<view-id>/index.md`는 `view`다.
   - view/component/frame id가 경로 id와 일치하는지 확인한다.
   - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다.
   - view/component/definition-index의 frontmatter `source_evidence`는 list이고 각 항목은 `type`, `path`, `notes`를 가져야 한다.
   - 이 문서들의 `source_evidence.type`은 `code`, `docs`, `user` 중 하나여야 한다.
   - 근거 파일이 없으면 `path: null`이어야 하며, placeholder 문자열을 근거로 보지 않는다.
   - view는 frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하는지 확인한다.
   - component는 frontmatter의 `status`, `source_evidence`와 본문 `Status`, `Source Evidence`가 충돌하는지 확인한다.
   - frame-view는 frontmatter `regions`와 본문 `Required Regions`가 충돌하는지 확인한다. frame-view에는 `status`나 `Source Evidence`를 요구하지 않는다.
   - view/component의 `Status`는 `구현됨`, `계획`, `가정`, `불명확` 중 하나여야 한다.
   - `구현됨` 항목은 코드 반영 완료 상태여야 한다. 코드 근거가 있으면 실제 존재하는 code evidence path를 가져야 한다.
   - `구현됨`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `계획`으로 낮추고 USER_REVIEW를 남길 수 있다.
   - `가정`, `불명확` 항목이 코드 동기화 가능한 정의처럼 설명되면 자동 의미 변경하지 않고 USER_REVIEW로 남긴다.
   - view와 frame-view의 region id가 `<view-id>.<region>` 또는 `<view-id>.<region>.<subregion>` 형식인지 확인한다.
   - view 문서에서 참조한 component id가 component 목록에 있는지 확인한다.
   - 없는 component가 단순 누락이고 생성 의도가 명확하면 `repair=true`일 때 component skeleton을 만들고 `Status`와 `Source Evidence`를 채운다.
   - 새 component로 만들지 기존 component로 바꿀지 판단이 필요하면 USER_REVIEW로 남긴다.

4. **frame 정합성 검사**
   - view가 있는데 대응 frame index가 없어도 visual source가 없으면 정상으로 본다.
   - visual source 파일이 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다.
   - frame index가 있는데 `visual_source: null`이고 해당 view 아래 visual source 파일도 없으면 `repair=true`일 때 빈 frame index 삭제 후보로 본다.
   - frame index가 가리키는 definition 경로가 실제 존재하는지 확인한다.
   - `visual_source`가 `null`이면 legacy/empty frame 후보로 보고 visual source 파일 존재 여부를 함께 확인한다.
   - `visual_source`가 값이면 해당 파일이 실제 존재하는지 확인한다.
   - `visual_source`가 `.excalidraw`이면 JSON으로 읽고 `elements`의 text label 또는 `customData.region_id`에서 region id 후보를 수집한다.
   - Excalidraw region id 후보가 있으면 frame required region, view definition region과 비교한다.
   - Excalidraw region id 후보가 없고 frame required region이 있으면 USER_REVIEW로 남긴다.
   - Excalidraw에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동 수정하지 않고 USER_REVIEW로 남긴다.
   - Excalidraw가 JSON으로 파싱되지 않으면 visual source 손상 또는 형식 불일치로 보고한다.
   - frame required region과 view definition region을 비교한다.
   - visual source가 있는 frame index에서 definition region이 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다.
   - 기존 frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다.
   - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다.

5. **구현 정합성 검사**
   - `scope=view:<view-id>` 또는 `scope=component:<component-id>`이면 해당 문서의 `source_evidence` 중 `type: code` 경로만 확인하고 전체 코드 후보 스캔은 하지 않는다.
   - `scope=all` 또는 `scope=implementation`이면 전체 view/component의 `source_evidence` 중 `type: code` 경로가 실제 존재하는지 확인한다.
   - 실제 UI 구현 후보를 찾는다.
     - 이 후보 스캔은 `scope=all` 또는 `scope=implementation`일 때만 수행한다.
     - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일
     - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다.
     - 코드가 많으면 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다.
   - 운영 단계에서는 코드 후보만 보고 agent-ui view/component를 새로 만들지 않는다.
   - 코드 후보가 명확한 route/page/view/shell인데 agent-ui에 대응 view가 없으면 USER_REVIEW로 남기거나, 사용자가 코드 기준 반영을 명시한 경우 `update-agent-ui`로 돌린다.
   - 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action인데 agent-ui에 대응 component가 없으면 USER_REVIEW로 남기거나, 사용자가 코드 기준 반영을 명시한 경우 `update-agent-ui`로 돌린다.
   - 코드 결과물이 `구현됨` 상태의 agent-ui 정의와 어긋난다는 사용자 보고가 있으면 해당 항목을 `계획`으로 낮추고 sync intent를 만든다.
   - 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다.
   - 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 `구현됨`을 `계획`으로 낮출 수 있다.

6. **USER_REVIEW 생성 또는 갱신**
   - active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다.
   - 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다.
   - 같은 경로와 같은 질문의 중복 항목은 만들지 않는다.
   - 항목에는 `Source Skill: validate-agent-ui`, `Stage: document-consistency`, `Blocking Step`, Context, Options, Needed For를 포함한다.

7. **code sync intent 판정**
   - `sync-intent=inherited`이면 `update-agent-ui`가 전달한 판단을 그대로 사용하고 재판단하지 않는다.
   - 수동 호출이거나 `sync-intent=auto`이면 agent-ui 변경분과 `계획` 상태 항목을 보고 `sync-agent-ui` 필요 여부를 판단한다.
   - `sync-intent=required`이면 validate 결과가 PASS 또는 자동 보정 완료 WARN이고 현재 범위에 미해결 USER_REVIEW가 없을 때 `sync-agent-ui`를 실행한다.
   - `sync-intent=skip`이면 code sync 필요 여부를 보고만 하고 실행하지 않는다.
   - 현재 범위에 `가정` 또는 `불명확` 항목이 있거나 미해결 USER_REVIEW가 있으면 `sync-agent-ui`를 실행하지 않는다.
   - `sync-agent-ui`를 실행할 때는 이 스킬의 보정 결과를 입력으로 넘기고, 순서를 바꾸지 않는다.

8. **결과 판정**
   - `PASS`: 자동 수정도 USER_REVIEW도 필요 없는 상태
   - `WARN`: 자동 수정이 있었거나 USER_REVIEW가 생성/갱신된 상태
   - `FAIL`: 구조가 너무 모호해서 자동 보정과 리뷰 작성 모두 불완전한 상태

## 자동 수정 허용 범위

- 누락된 필수 디렉터리와 index 문서 생성
- 명확한 단일 후보 visual source 등록
- 명확한 단일 후보 상대 링크 보정
- visual source가 있는 frame index의 region 누락 보완
- 빈 archive/user-review 디렉터리 생성
- 템플릿 필수 섹션과 frontmatter 누락 보완. 모든 문서의 `ui_doc_type`, view/component의 `Source Evidence`와 `Status`, 문서 유형별 필수 필드 누락 포함
- 명시된 code evidence 경로가 실제 존재하지 않는 `구현됨`을 `계획`으로 낮추고 USER_REVIEW를 남기는 보정

## USER_REVIEW 대상

- 정의에는 없는 region이 기존 frame-view에 있고 추가/삭제 의도 판단이 필요한 경우
- frame-view가 있는데 frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우
- component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우
- 운영 단계에서 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우
- 운영 단계에서 코드에만 있는 view/component를 agent-ui에 반영할지 판단이 필요한 경우
- 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우
- `계획` 항목을 코드로 반영하려 했지만 구현 방향, 환경, 권한, 검증 실패를 에이전트가 해결하지 못한 경우
- `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우
- drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우

## 실행 결과 검증

- [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가
- [ ] 활성 Markdown 문서가 유효한 `ui_doc_type` frontmatter를 갖는가
- [ ] folder-first + `index.md` 구조가 유지되는가
- [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가
- [ ] 명시된 code evidence 경로가 깨진 `구현됨`이 남아 있지 않은가
- [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보와 agent-ui 불일치가 sync intent 또는 USER_REVIEW로 분리되었는가
- [ ] view/component/frame 참조가 끊기지 않는가
- [ ] visual source가 없는 view는 frame 참조가 `null`이거나 비어 있는 frame-view가 없는가
- [ ] 자동 수정한 파일 목록이 보고되는가
- [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가
- [ ] archive 본문을 일반 검증에서 읽지 않았는가
- 검증 실패 시: 판정을 `FAIL`로 보고하고 자동 수정하지 못한 이유를 남긴다.

## 출력 형식

```md
## agent-ui 검증 결과: <PASS|WARN|FAIL>

- Scope: <scope>
- Auto Fixed: <파일/항목 목록 또는 없음>
- User Review: <agent-ui/USER_REVIEW.md 생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>
- Checked Files: <활성 파일 목록>
- Sync Intent: <inherited|required|skip|auto 판단 결과>
- sync-agent-ui: <실행/보류/생략 사유>
```

## 금지 사항

- UI 의도 판단이 필요한 문제를 자동 수정하지 않는다.
- archive 본문을 일반 검증 컨텍스트로 읽지 않는다.
- `.excalidraw` 내용을 현재 UI 기준으로 단독 확정하지 않는다.
- 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다.
- agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다.
- 전달받은 sync intent가 있으면 같은 내용을 재판단하지 않는다.
- `sync-agent-ui`보다 뒤에 실행되어서는 안 된다.
- 운영 단계에서 코드 후보만 근거로 agent-ui view/component skeleton을 자동 생성하지 않는다.
