---
name: validate-agent-ui
version: 1.1.0
description: agent-ui scaffold, definition/frame/component/source evidence/status 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬
---

# validate-agent-ui

## 목적

`agent-ui/` 구조와 문서 간 정합성을 검사한다.
파일 규약처럼 결정적으로 고칠 수 있는 문제는 자동 보정하고, 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 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때

## 입력

- `scope`: `all`, `view:<view-id>`, `component:<component-id>`, `frame:<view-id>` 중 하나. 기본값은 `all` (선택)
- `repair`: `true` 또는 `false`. 기본값은 `true` (선택)

## 먼저 확인할 것

- [ ] `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 문서만 읽는다.
- [ ] 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 목록을 만든다.
   - 같은 레벨의 `<name>.md`와 `<name>/` 혼재 여부를 확인한다.

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

3. **definition 정합성 검사**
   - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다.
   - `Status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나여야 한다.
   - `implemented` 항목은 실제 존재하는 코드 근거가 있어야 한다.
   - `implemented`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `unknown`으로 낮추고 USER_REVIEW를 남길 수 있다.
   - `implemented`인데 code evidence 자체가 없으면 자동 변경하지 않고 USER_REVIEW로 남긴다.
   - `planned`, `assumed`, `unknown` 항목이 구현 완료처럼 설명되면 자동 의미 변경하지 않고 USER_REVIEW로 남긴다.
   - 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가 없으면 `repair=true`일 때 만든다.
   - frame index가 가리키는 definition 경로와 visual source가 실제 존재하는지 확인한다.
   - frame required region과 view definition region을 비교한다.
   - definition에 있는 region이 frame index에만 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다.
   - frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다.
   - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다.

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

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

## 자동 수정 허용 범위

- 누락된 필수 디렉터리와 index 문서 생성
- 명확한 단일 후보 visual source 등록
- 명확한 단일 후보 상대 링크 보정
- definition에 이미 있는 region의 frame index 누락 보완
- 빈 archive/user-review 디렉터리 생성
- 템플릿 필수 섹션 누락 보완. `Source Evidence`와 `Status` 누락 포함
- 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다.
- 명시된 code evidence 경로가 실제 존재하지 않는 `implemented`를 `unknown`으로 낮추고 USER_REVIEW를 남기는 보정

## USER_REVIEW 대상

- 정의에는 없는 region이 frame에 있고 추가/삭제 의도 판단이 필요한 경우
- frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우
- component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우
- `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우
- drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우

## 실행 결과 검증

- [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가
- [ ] folder-first + `index.md` 구조가 유지되는가
- [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가
- [ ] 명시된 code evidence 경로가 깨진 `implemented`가 남아 있지 않은가
- [ ] view/component/frame 참조가 끊기지 않는가
- [ ] 자동 수정한 파일 목록이 보고되는가
- [ ] 사용자 판단이 필요한 항목이 `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: <활성 파일 목록>
```

## 금지 사항

- UI 의도 판단이 필요한 문제를 자동 수정하지 않는다.
- archive 본문을 일반 검증 컨텍스트로 읽지 않는다.
- `.excalidraw` 내용을 현재 UI 기준으로 단독 확정하지 않는다.
- 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다.
- agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다.
