pro-design-brief · diff
git:20261021.70b7e84 to git:20261021.1d40277
100 added, 98 removed. Audit A to A.
---
name: pro-design-brief
description: "Build a design request for a designer from a screen you already built: capture real states, render layout alternatives, collect copy and must-keep rules, deliver as issue, HTML or md. Use for 'request a design', 'send to designer'."
---
- # 디자인 요청서 — 시안보다 먼저 만든 화면
+ # Design request: for a screen built before its design
## When to use
- - '디자인 요청해줘', '시안 요청 올려줘', '디자이너한테 보낼 거 만들어줘'
- - '이거 디자인 안 나왔는데 먼저 만들었어', '빈 화면이랑 에러 화면도 그려 달라고 해줘', '디자인 이슈 만들어줘'
- - 시안을 코드로 옮기고 대조하는 것은 pro-figma, 버그를 찾는 것은 pro-agent-test 다.
- - Figma 링크가 있으면 시안에 그려진 상태와 빠진 상태를 가려 빈틈을 요청한다. 정답이 아니라 생각할 재료를 준다.
+ - "Request a design", "post a design request", "make something to send to the designer" (Korean: '디자인 요청해줘', '시안 요청 올려줘', '디자이너한테 보낼 거 만들어줘')
+ - "There's no design for this yet but I built it first", "ask them to draw the empty and error screens too", "create a design issue" (Korean: '이거 디자인 안 나왔는데 먼저 만들었어', '빈 화면이랑 에러 화면도 그려 달라고 해줘', '디자인 이슈 만들어줘')
+ - Turning a design into code and comparing it is pro-figma; finding bugs is pro-agent-test.
+ - If there is a Figma link, separate the states drawn in the design from the missing ones and request the gaps. Give material to think with, not the answer.
- 화면이 먼저 만들어지고 시안은 나중에 온다. **디자이너는 보통 기본 화면만 그린다** — 비었을 때·실패했을 때·
- 글자가 길 때가 빠진다. 이 스킬은 그 빈자리를 먼저 채운 요청서를 만든다.
+ The screen gets built first and the design comes later. **Designers usually draw only the default screen.** Empty, failed and
+ long-text cases go missing. This skill builds a request that fills those gaps first.
- > **정답을 주지 않는다. 생각할 재료를 준다.** 대안·문구·요소를 넓게 펼치고, 개발 쪽 선호는 근거와 함께 한 줄.
- > **반드시 디자이너가 받아 보는 결과물로 끝난다** — 이미지가 든 이슈 / HTML 한 장 / md 폴더. 채팅 요약으로 끝내지 않는다.
+ Talk to the user in the user's language (or the configured `language` preference). Write the brief in the configured `language`; if none is set, match the repo's design request template or the user's language.
- | 쓴다 | 쓰지 않는다 |
+ > **Do not give the answer. Give material to think with.** Lay out alternatives, copy and elements broadly; state the dev side's preference in one line with its reason.
+ > **Always end with a deliverable the designer receives**: an issue with images / one HTML page / an md folder. Never end with a chat summary.
+
+ | Use it | Do not use it |
|---|---|
- | 시안 없이 먼저 구현했다 → 시안 요청 | 시안이 있고 코드로 옮기는 중 → `pro-figma` |
- | 시안이 기본 화면만 있다 → 빠진 상태 요청 | 버그 찾기 → `pro-agent-test` |
- | 디자이너가 방향을 못 잡는다 → 재료 제공 | 디자인 시스템을 새로 짠다 |
+ | Implemented without a design → request a design | A design exists and you are coding it → `pro-figma` |
+ | The design has only the default screen → request missing states | Finding bugs → `pro-agent-test` |
+ | The designer cannot find a direction → provide material | Building a new design system |
- `../references/common-rules.md` 의 **절대 규칙** 적용. 설정은 `../references/config-rules.md` §2~4, 승인 게이트는
- `../references/approval-and-questions.md`. **대화에 이미 있는 것은 다시 조사하지 않는다** — 특히 "왜 이 자리를 골랐나"는
- 대화에만 있으니 반드시 살린다. 인자: $ARGUMENTS
+ Apply the **absolute rules** in `../references/common-rules.md`. Settings: §2–4 of `../references/config-rules.md`; approval gate:
+ `../references/approval-and-questions.md`. **Do not re-investigate what is already in the conversation.** In particular, "why this placement was chosen"
+ exists only in the conversation, so always keep it. Arguments: $ARGUMENTS
- ## 무엇을 하려는가 → 명령 → 자세한 문서
+ ## Goal → command → details
- | 하려는 것 | 명령 | 자세히 |
+ | Goal | Command | Details |
|---|---|---|
- | 출력 방식 · 디자이너 · 게시 전 확인 판정/저장 | `design_brief_cli.py config show\|set` | 아래 0단계 |
- | Figma · 이미지 입력 읽기, 빈틈 표 | `mcp__figma__get_figma_data` · `figma_cli.py coverage` | `references/states-and-capture.md` |
- | 상태 목록(5축) | — (코드를 읽는다) | `references/states-and-capture.md` · `../references/design-states.md` |
- | 캡처 자리 · 실기기/브라우저/렌더 캡처 | `launch_cli.py get-output-path --skill design-brief` · `app shot` · `web route` · `render run` | `references/states-and-capture.md` |
- | 렌더할 수 없는 상태 · 아직 없는 안 | `design_brief_cli.py ascii --spec` | `references/states-and-capture.md` |
- | 대안 · 문구 · UI 요소 · 꼭 지킬 것 | `design_brief_cli.py copy-lint` | `references/content.md` |
- | 보드 조립(HTML → 주제별 PNG · md) | `design_brief_cli.py get-output-path` → `board` | `references/publishing.md` |
- | 게시(이슈 · HTML · md) | `github_cli.py upload-image` → `design_brief_cli.py rewrite-images` → `create-issue` | `references/publishing.md` |
+ | Decide/save output mode · designer · confirm-before-posting | `design_brief_cli.py config show\|set` | Step 0 below |
+ | Read Figma · image input, gap table | `mcp__figma__get_figma_data` · `figma_cli.py coverage` | `references/states-and-capture.md` |
+ | State list (5 axes) | — (read the code) | `references/states-and-capture.md` · `../references/design-states.md` |
+ | Capture slot · device/browser/render capture | `launch_cli.py get-output-path --skill design-brief` · `app shot` · `web route` · `render run` | `references/states-and-capture.md` |
+ | States that cannot be rendered · options that do not exist yet | `design_brief_cli.py ascii --spec` | `references/states-and-capture.md` |
+ | Alternatives · copy · UI elements · must-keep rules | `design_brief_cli.py copy-lint` | `references/content.md` |
+ | Assemble the board (HTML → per-topic PNG · md) | `design_brief_cli.py get-output-path` → `board` | `references/publishing.md` |
+ | Publish (issue · HTML · md) | `github_cli.py upload-image` → `design_brief_cli.py rewrite-images` → `create-issue` | `references/publishing.md` |
- ## 스크립트 찾기 — 한 번만
+ ## Find the scripts: once
- **Bash 도구는 호출마다 상태가 초기화된다.** 한 번 찾고 **실제 경로를 이후 블록에 값으로 써넣는다.**
+ **The Bash tool resets its state on every call.** Find them once and **write the real paths as literal values in later blocks.**
```bash
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PYTHON=$(for _py in python3 python; do _path=$(command -v "$_py" 2>/dev/null) || continue; "$_path" -c "import sys; sys.exit(0)" 2>/dev/null && echo "$_path" && break; done)
[ -z "$PYTHON" ] && { echo "Python not found"; exit 1; }
for SKILL in pro-design-brief pro-launch pro-github pro-figma; do
ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
[ -d "$ROOT/skills/$SKILL/scripts" ] || for B in ~/.claude/plugins/cache ~/.codex/plugins/cache ~/.gemini/extensions ~/.pi/agent/git; do
H=$(find "$B" -maxdepth 8 -type d -path "*/projectops/*skills/$SKILL/scripts" 2>/dev/null | sort -V | tail -1)
[ -n "$H" ] && { ROOT="${H%/skills/$SKILL/scripts}"; break; }
done
- [ -d "$ROOT/skills/$SKILL/scripts" ] || { echo "$SKILL 스크립트를 찾지 못했습니다"; exit 1; }
+ [ -d "$ROOT/skills/$SKILL/scripts" ] || { echo "$SKILL scripts not found"; exit 1; }
echo "$SKILL=$ROOT/skills/$SKILL/scripts"
done
```
- 자리표시: `{SCRIPTS}` = pro-design-brief(config · get-output-path · board · copy-lint · ascii · rewrite-images), `{LAUNCH}` = pro-launch(캡처 · 렌더 · 상태 연출),
- `{GITHUB}` = pro-github(이미지 · 이슈), `{FIGMA}` = pro-figma(Figma 덤프 세기 — 링크가 있을 때).
+ Placeholders: `{SCRIPTS}` = pro-design-brief (config · get-output-path · board · copy-lint · ascii · rewrite-images), `{LAUNCH}` = pro-launch (capture · render · staging states),
+ `{GITHUB}` = pro-github (images · issues), `{FIGMA}` = pro-figma (counting the Figma dump, when there is a link).
- ## 공통 규칙
+ ## Common rules
- - 흐름: `0 설정 → 1 입력 → 2 상태 목록 → 3 캡처 → 4 대안·문구·UI·꼭 지킬 것 → 5 보드 → 6 게시`.
- - **"지금 앱은 이렇다"의 근거는 실기기·운영 API 다.** 렌더는 상태를 연출하는 수단이다(렌더만 보고 쓴 주장이 실기기와 7건 달랐다).
- 캡처마다 `source`, 사실 문장은 `facts[]` 에 `basis` 와 함께. 수치는 픽스처가 아니라 운영 값.
- - 상태는 **네가 코드를 읽고** 적는다. 상태마다 `status`(done · temp · none) 와 `reachable`(yes · old_data · unknown) —
- 입력 경로가 지금도 있는지 코드로 본다. 서버가 내려주는 문구(공지 · 약관 · 오류)도 상태다.
- - 기기 화면 이동은 **요소로 누른다**(`app tap --text|--id|--desc`, 모르면 `app tree`). 좌표 눈대중 · 호스트 마우스 금지.
- - 대안은 **축이 다른 3~5안**, "현재 구현"·"최소" 안을 항상 포함. 법적 문구는 후보를 내지 않는다(`legal: true`).
- - 캡처를 위해 AI 생성 API 를 부르지 않는다. `residue` 는 네가 만든 것만 지운다. 디자이너 대신 결정하지 않는다.
- - **사용자에게 설정 키 이름·파일 경로를 보이지 않는다.**
+ - Flow: `0 settings → 1 input → 2 state list → 3 capture → 4 alternatives · copy · UI · must-keep → 5 board → 6 publish`.
+ - **Evidence for "this is how the app is now" comes from a real device and the production API.** Rendering is a way to stage states (claims written from renders alone differed from the real device in 7 places).
+ Give each capture a `source`, and put factual statements in `facts[]` with a `basis`. Numbers come from production values, not fixtures.
+ - **You read the code** and list the states. Each state gets a `status` (done · temp · none) and `reachable` (yes · old_data · unknown);
+ check in the code whether the input path still exists. Text the server sends (notices, terms, errors) is also a state.
+ - Navigate device screens **by element** (`app tap --text|--id|--desc`; if unsure, `app tree`). No guessing coordinates, no host mouse.
+ - Alternatives: **3 to 5 options on different axes**, always including a "current implementation" and a "minimal" option. Offer no candidates for legal text (`legal: true`).
+ - Do not call AI generation APIs to make captures. Clean up only the `residue` you created. Do not decide for the designer.
+ - **Do not show config key names or file paths to the user.**
- ## 0. 설정 판정 — 처음 한 번, 이후 자동
+ ## 0. Settings: decide once, automatic afterwards
```bash
PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py config show --root {PROJECT_ROOT}
```
- `resolved` 에 세 가지가 나온다. `missing` 에 있는 것만 **한 번에 하나씩**, 권장안을 1번에 두고 묻는다.
+ `resolved` shows three items. Ask only about those in `missing`, **one at a time**, with the recommended option first.
- | 정할 것 | 자동 판정 (`suggest`) | 물을 때 |
+ | To decide | Automatic decision (`suggest`) | When asking |
|---|---|---|
- | 출력 방식 | GitHub 레포면 `issue`, 아니면 `html` | "디자인 요청서를 어떻게 받으세요? 1) 디자인 이슈 (권장) 2) HTML 한 장 3) md 폴더" |
- | 디자이너 | 이슈 템플릿의 `디자인:` 줄(`designer_candidates`). 비면 최근 디자인 이슈 담당자를 `{GITHUB}` 로 | "디자이너 GitHub 아이디(또는 이름)가 뭔가요?" |
- | 게시 전 확인 | 기본은 확인받는다 | 첫 게시 때 승인 게이트 C 분기 |
+ | Output mode | `issue` for a GitHub repo, else `html` | "How do you want the design request? 1) Design issue (recommended) 2) One HTML page 3) md folder" |
+ | Designer | The `디자인:` line in the issue templates (`designer_candidates`). If empty, the assignee of recent design issues via `{GITHUB}` | "What is the designer's GitHub ID (or name)?" |
+ | Confirm before posting | Confirm by default | Approval gate branch C on the first post |
```bash
- PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py config set --root {PROJECT_ROOT} --destination issue --designer {아이디}
- # --scope default : 모든 레포 기본값으로 ("앞으로 전부") --auto-approve true : "다음부턴 확인 없이 올려줘"
+ PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py config set --root {PROJECT_ROOT} --destination issue --designer {id}
+ # --scope default : default for all repos ("from now on, everywhere") --auto-approve true : "post without asking next time"
```
- "다음부턴 HTML 로 해줘"도 같은 명령이다. GitHub 을 안 쓰는 레포는 경로로 맞춘다(`github` 설정과 따로 두는 이유).
+ "Use HTML from now on" is the same command. Repos that do not use GitHub are matched by path (the reason this is kept apart from the `github` settings).
- ## 1~4. 입력 · 상태 · 캡처 · 재료
+ ## 1–4. Input · states · capture · material
- 구현 여부(구현됨 / 일부 / 아직 없음)를 정하고, Figma 가 있으면 그려진 상태 vs 빠진 상태 빈틈 표를 만든다.
- 5축(데이터 · 입력 · 환경 · 사람 · 표시)에서 **그 화면에 해당하는 상태만** 뽑는다. 순서는 `references/states-and-capture.md`.
+ Decide whether it is implemented (implemented / partial / not yet), and if there is a Figma file, build the gap table of drawn vs missing states.
+ From the 5 axes (data · input · environment · person · display), pick **only the states that apply to that screen**. Order: `references/states-and-capture.md`.
```bash
- PYTHONIOENCODING=utf-8 {PYTHON} {LAUNCH}/launch_cli.py get-output-path --skill design-brief --title "{화면 이름}"
- source "{env_file 값}" # $SHOT_DIR · $RUN_DIR · $DEV
- PYTHONIOENCODING=utf-8 {PYTHON} {LAUNCH}/launch_cli.py device acquire --platform ios --purpose "디자인 요청 {화면}" # 앱이면 빌린다 · 끝나면 device release
- PYTHONIOENCODING=utf-8 {PYTHON} {LAUNCH}/launch_cli.py app shot --device "$DEV" --out 01_현재 --clean-status
+ PYTHONIOENCODING=utf-8 {PYTHON} {LAUNCH}/launch_cli.py get-output-path --skill design-brief --title "{screen name}"
+ source "{env_file value}" # $SHOT_DIR · $RUN_DIR · $DEV
+ PYTHONIOENCODING=utf-8 {PYTHON} {LAUNCH}/launch_cli.py device acquire --platform ios --purpose "design request {screen}" # borrow a device for an app · device release when done
+ PYTHONIOENCODING=utf-8 {PYTHON} {LAUNCH}/launch_cli.py app shot --device "$DEV" --out 01_current --clean-status
PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py ascii --spec '{"title":"…","rows":["…","---"],"width":24}'
- PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py copy-lint --file {보드 데이터.json} --banned "아이,기기,서버"
+ PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py copy-lint --file {board data.json} --banned "kid,device,server"
```
- 캡처 순서는 **코드 렌더 → 실기기·브라우저 → ASCII**. 대안 · 문구(`현재 → 후보 2~3 → 이유`) · UI 요소(레포에 있는 것 먼저) ·
- 꼭 지킬 것(브랜드 규격 · 디자인 원칙 · 코드 주석의 합의된 예외 — 부딪히면 질문으로)은 `references/content.md`.
+ Capture order is **code render → real device / browser → ASCII**. Alternatives, copy (`current → 2–3 candidates → reason`), UI elements (what the repo already has first) and
+ must-keep rules (brand specs, design principles, agreed exceptions in code comments; raise conflicts as questions) are in `references/content.md`.
- ## 5. 보드 — HTML 한 장 → 주제별 PNG
+ ## 5. Board: one HTML page → per-topic PNG
- 모은 것을 **데이터 JSON** 하나로 적고 조립한다(그림 경로는 데이터 파일 기준 상대경로).
+ Write everything you collected into one **data JSON** and assemble it (image paths relative to the data file).
```bash
- PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py get-output-path --title "{화면 이름}" # 캡처와 같은 제목
+ PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py get-output-path --title "{screen name}" # same title as the captures
PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py board --data {run_dir}/board_data.json --out {run_dir}/board --png
- # --md : brief.md 도 만든다 --strict : preflight 가 남으면 ok:false 로 멈춘다 (게시 직전)
+ # --md : also writes brief.md --strict : stops with ok:false if preflight items remain (right before publishing)
```
```json
{
- "title": "{화면} — 디자인 요청서",
- "summary": {"what": "", "why": "", "status": "", "recommend": "A안 — 근거 한 줄", "note": "",
- "must_keep": [{"rule": "", "source": "파일·이슈·문서"}]},
- "facts": [{"claim": "주간 지급량은 50개다", "basis": "device|server|code|design", "ref": "GET /api/credit · 캡처 파일"}],
- "current": [{"label": "로그인 (iOS)", "image": "screenshots/login_ios.png", "source": "device"},
- {"label": "버전 4배", "image": "screenshots/zoom.png", "zoom": true, "source": "device"}],
- "states": [{"axis": "데이터", "name": "0건", "status": "done|temp|none", "reachable": "yes|old_data|unknown",
+ "title": "{screen} — design request",
+ "summary": {"what": "", "why": "", "status": "", "recommend": "Option A — one-line reason", "note": "",
+ "must_keep": [{"rule": "", "source": "file · issue · doc"}]},
+ "facts": [{"claim": "The weekly grant is 50", "basis": "device|server|code|design", "ref": "GET /api/credit · capture file"}],
+ "current": [{"label": "Login (iOS)", "image": "screenshots/login_ios.png", "source": "device"},
+ {"label": "Version at 4x", "image": "screenshots/zoom.png", "zoom": true, "source": "device"}],
+ "states": [{"axis": "Data", "name": "0 items", "status": "done|temp|none", "reachable": "yes|old_data|unknown",
"image": "", "source": "render|device|server", "ascii": "",
"copy": "", "copy_needed": false, "design": true, "render_failed": false}],
"alternatives": [{"id": "A", "name": "", "image": "", "source": "render", "zoom": "", "ascii": "",
"recommended": true, "pros": [], "cons": [], "dev_impact": ""}],
"copy": [{"where": "", "current": "", "candidates": [], "reason": "", "legal": false, "needed": false}],
- "ui": [{"shape": "목록", "candidates": [], "existing": [], "new": []}],
- "impact": [{"choice": "B안", "work": "따로 필요한 개발"}]
+ "ui": [{"shape": "List", "candidates": [], "existing": [], "new": []}],
+ "impact": [{"choice": "Option B", "work": "extra development needed"}]
}
```
- **PNG 를 Read 로 열어 본다.** **`preflight` 가 비어야 게시한다.** 조립 규칙은 `references/publishing.md`.
+ **Open the PNGs with Read.** **Publish only when `preflight` is empty.** Assembly rules: `references/publishing.md`.
- **미리보기만 하고 싶을 때** (게시 전에 사람이 먼저 본다): `board` 는 게시하지 않는다 — `--png` 로 만든 주제별 PNG 와 `brief.md` 를 `Read` 로 열어
- 사용자에게 보여주고 승인받은 뒤에 6단계로 간다. PIL 로 컨택트 시트를 따로 만들지 않는다. 보여줄 때 **ASCII 로 대체한 그림이 있으면 개수를 같이 말한다**.
+ **When you only want a preview** (a person looks before publishing): `board` does not publish. Open the per-topic PNGs from `--png` and `brief.md` with `Read`,
+ show them to the user, and go to Step 6 only after approval. Do not build a separate contact sheet with PIL. When showing them, **state how many images were replaced with ASCII, if any**.
- ## 6. 게시 — 디자이너에게는 한 형식만
+ ## 6. Publish: only one format for the designer
- 게시 직전 승인 게이트(`approval-and-questions.md` §4 A/B/C) — 제목·담당자·첨부 장수를 보이고 승인받는다.
- `html` 은 `board/board.html`, `markdown` 은 `board/brief.md` + PNG 폴더 경로를 알려준다. **둘 다 주지 않는다.**
- `issue` 면 **그림 먼저**(본문을 먼저 올리면 그림 없는 글이 게시된다):
+ Approval gate right before publishing (`approval-and-questions.md` §4 A/B/C): show the title, assignee and number of attachments, and get approval.
+ For `html`, give the path of `board/board.html`; for `markdown`, `board/brief.md` plus the PNG folder. **Never give both.**
+ For `issue`, **images first** (if you post the body first, a post without images goes out):
```bash
PYTHONIOENCODING=utf-8 {PYTHON} {GITHUB}/github_cli.py upload-image {owner} {repo} {run_dir}/board/*.png --prefix brief > {run_dir}/uploads.json
- PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py rewrite-images --md "{본문 .md 경로}" --uploads {run_dir}/uploads.json # → <본문>.issue.md
- PYTHONIOENCODING=utf-8 {PYTHON} {GITHUB}/github_cli.py create-issue {owner} {repo} "{제목}" "{<본문>.issue.md 경로}" "{라벨}" --assignees "{디자이너}"
- PYTHONIOENCODING=utf-8 {PYTHON} {GITHUB}/github_cli.py add-comment {owner} {repo} {구현 이슈} "{링크 댓글 .md}" # 구현 이슈와 서로 링크
+ PYTHONIOENCODING=utf-8 {PYTHON} {SCRIPTS}/design_brief_cli.py rewrite-images --md "{body .md path}" --uploads {run_dir}/uploads.json # → <body>.issue.md
+ PYTHONIOENCODING=utf-8 {PYTHON} {GITHUB}/github_cli.py create-issue {owner} {repo} "{title}" "{<body>.issue.md path}" "{labels}" --assignees "{designer}"
+ PYTHONIOENCODING=utf-8 {PYTHON} {GITHUB}/github_cli.py add-comment {owner} {repo} {implementation issue} "{link comment .md}" # link it with the implementation issue both ways
```
- 본문은 레포 디자인 요청 템플릿(🖌️ 요청 내용 · 🎯 기대 결과 · 📋 참고 자료 · 💡 추가 요청 사항 · 🙋 담당자)에 보드와 같은
- 이름·순서로 맞춘다. 게시 뒤 틀린 것은 본문 수정 + **정정 댓글**(처음 → 실제 → 근거). `references/publishing.md`.
+ Match the body to the repo's design request template (🖌️ Request · 🎯 Expected result · 📋 References · 💡 Additional requests · 🙋 Assignees, or the Korean template's equivalents), using the same
+ names and order as the board. If something is wrong after publishing, edit the body and add a **correction comment** (initial → actual → evidence). See `references/publishing.md`.
- ## 실패 경로 → 다음 행동
+ ## Failure path → next action
- | code · 상황 | 동작 |
+ | code · situation | Action |
|---|---|
- | `browser_missing` · `png_failed` | PNG 대신 HTML 또는 원본 캡처 + md 표로 낸다. 요약에 사유. 브라우저가 필요하면 묻고 `launch_cli.py web setup` |
- | `preflight_failed` | 출처 없는 캡처 · `reachable` 없는 상태 · 렌더만 근거인 사실을 고치거나 뺀다 |
- | `candidate_issues` (copy-lint) | 걸린 후보를 네가 고친다 |
- | `bad_data` · `bad_file` · `bad_spec` | JSON 형식을 고친다(ascii 는 `title` · `rows` · `width` · `caption` 만) |
- | `bad_destination` · `nothing_to_set` | `--destination issue\|html\|markdown`, 바꿀 값을 하나 이상 준다 |
- | 렌더 실패 | 그 상태만 ASCII 로 대체하고 `render_failed: true` |
- | 업로드 실패 · `private_warning` | 로컬 산출물 경로를 알린다. private 이면 `html` 로 바꿀지 묻는다 |
- | `unmatched_images` (rewrite-images) | `unmatched` 그림을 `upload-image` 로 올리고 그 출력도 `--uploads` 에 더해 다시. 인라인 파이썬으로 경로를 바꾸지 않는다 |
- | Figma 읽기 실패 · 디자이너 모름 | 없이 진행하고 요약에 적는다(담당자 없이 등록 → 다음에 묻는다) |
- | 대상 레포에 흔적(`residue`) | 그대로 보고하고 지우지 않는다(네가 만든 것만 지운다) |
- | 실기기로 확인할 수 없다(기기·계정·비용) | 그 사실은 `facts` 에서 빼거나 근거 없음으로 두고 "확인 못 함"으로 적는다. 렌더로 대신 단정하지 않는다 |
+ | `browser_missing` · `png_failed` | Deliver HTML, or raw captures plus an md table, instead of PNGs. Give the reason in the summary. If a browser is needed, ask, then `launch_cli.py web setup` |
+ | `preflight_failed` | Fix or drop captures without a source, states without `reachable`, and facts based only on renders |
+ | `candidate_issues` (copy-lint) | Fix the flagged candidates yourself |
+ | `bad_data` · `bad_file` · `bad_spec` | Fix the JSON format (ascii takes only `title` · `rows` · `width` · `caption`) |
+ | `bad_destination` · `nothing_to_set` | Use `--destination issue\|html\|markdown`, and give at least one value to change |
+ | Render failed | Replace only that state with ASCII and set `render_failed: true` |
+ | Upload failed · `private_warning` | Report the local output path. For a private repo, ask whether to switch to `html` |
+ | `unmatched_images` (rewrite-images) | Upload the `unmatched` images with `upload-image`, add that output to `--uploads` too, and run again. Do not rewrite paths with inline Python |
+ | Figma read failed · designer unknown | Continue without it and note it in the summary (file without an assignee → ask next time) |
+ | Leftovers (`residue`) in the target repo | Report them as they are and do not delete them (delete only what you created) |
+ | Cannot verify on a real device (device, account, cost) | Drop that fact from `facts` or leave it without a basis and write "not verified". Do not assert it from a render instead |
## Customize
Your own language, tone and rules apply: see `../references/preferences.md`. Read them once at the start: run the snippet in `../references/preferences.md` with `SKILL_ID=pro-design-brief`.
Keys for this skill: the common `language`, `tone`, `rules` only.
Preferences change presentation only; approval gates, secret protection and `--dry-run` stay in force.