/cc-quality:bug-report — 스크린샷만 주면 버그 리포트 자동 작성

이미지 분석 기반 버그 리포트 생성과 ZenHub 이슈 자동화

/cc-quality:bug-report — 스크린샷만 주면 버그 리포트 자동 작성#

항목	내용
실행 명령	`/cc-quality:bug-report`
분류	개발
MCP 서버	`zenhub`

한마디로#

오류 화면을 캡처해서 던지면, 무엇이 잘못됐는지 알아서 분석하고 정식 버그 리포트와 이슈(ZenHub/GitHub)를 자동으로 만들어 주는 명령입니다. "이 화면 이상한데?"라고 사진 한 장 보여주면, 알아서 보고서로 정리해 주는 비서라고 생각하면 됩니다.

누가·언제 쓰나요#

버그를 발견해서 이슈로 등록해야 할 때
스크린샷과 함께 버그 리포트를 작성하고 싶을 때
QA(품질 점검) 중 발견한 문제를 기록으로 남기고 싶을 때

무엇을 해주나요#

이미지 분석: 스크린샷 속 오류 메시지, 화면 상태, 깨진 레이아웃 등을 읽어 냅니다.
자동 분류: 버그 종류(UI/기능/크래시/성능/데이터)와 심각도(긴급~낮음)를 추천합니다.
이슈 자동 생성: ZenHub/GitHub에 제목·본문·라벨까지 갖춘 이슈를 만듭니다. 예) [Bug] 결제: 주문 상세가 표시되지 않음 형태의 이슈 #123
상태 정리: 심각도에 따라 이슈를 적절한 진행 단계(In Progress / Triage / Backlog)로 자동 이동시킵니다.

어떻게 쓰나요#

# 기본 (이미지 + 설명)
/cc-quality:bug-report /tmp/error_screenshot.png  " 결제 완료 후 주문 상세가 안 보임 " 

 # 텍스트만으로
/cc-quality:bug-report  " 로그인 버튼을 눌러도 반응이 없음 " 

 # 심각도 지정
/cc-quality:bug-report --severity critical  " 앱 시작 시 크래시 " 

 # 버그 종류 지정
/cc-quality:bug-report --type ui /tmp/layout.png  " 긴 텍스트에서 화면이 넘침 " 

 # 보고서만 만들고 이슈는 생성하지 않기
/cc-quality:bug-report --no-create  " 이건 테스트용 버그 "

설명(bug_description)은 꼭 필요하고, 이미지는 있으면 더 정확합니다. --severity(심각도), --type(종류), --no-create(이슈 생성 생략)는 선택 사항입니다.

안에서 무슨 일이 벌어지나요#

이미지 분석 — 스크린샷이 있으면 먼저 읽어서 화면 상태와 오류 메시지를 파악하고, 버그 종류·심각도를 추정합니다.
정보 수집 — 재현 방법, 기대했던 결과, 환경(OS·기기·앱 버전) 등 부족한 정보를 사용자에게 물어봅니다. 단 "기대했던 결과"가 사용자가 본 사실이 아니라 디자인 판단인 경우(예: 같은 값이 화면마다 다르게 표기됨 — 어느 쪽이 맞나)는 묻지 않고 cc-designer 의 의사결정 프로토콜로 정하고 그 근거를 리포트에 남깁니다.
이슈 생성 — 제목·본문·라벨을 갖춰 ZenHub/GitHub 이슈를 만들고, 심각도에 맞는 진행 단계로 이동시킵니다.
마무리 안내 — 만들어진 이슈 번호와 함께 다음 단계인 /cc-dev:bugfix(수정 시작)로 자연스럽게 이어 줍니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Triggers#

When a bug is found and an issue needs to be filed
When writing a bug report with screenshots
When documenting issues found during QA

Context Trigger Pattern#

/cc-quality:bug-report [image_path] [bug_description]

Parameters#

Parameter	Required	Description	Example
`image_path`	❌	Bug screenshot path	`/path/to/screenshot.png`
`bug_description`	✅	Brief description of the bug	`"Login button is not working"`
`--severity`	❌	Specify severity	`critical`, `high`, `medium`, `low`
`--type`	❌	Specify bug type	`ui`, `function`, `crash`, `performance`, `data`
`--no-create`	❌	Report only without issue creation	-

Behavioral Flow#

Step 1: Image Analysis (when image is provided)#

## Image Analysis

Analyze screenshot using the Read tool:

1. **Identify UI state**
   - Error dialog displayed
   - Empty State screen
   - Loading state persisting
   - Layout broken

2. **Extract text**
   - Error messages
   - Screen title
   - Button text

3. **Bug classification inference**
   - Automatic bug type classification
   - Severity recommendation
   - Impact area identification

Step 2: Information Gathering#

## Information Gathering

Collect additional information via AskUserQuestion:

1. **Reproduction steps** (required)
   - State before bug occurred
   - Actions performed
   - When bug occurred

2. **Expected result** (required)
   - Expected result during normal operation
   - ⚠️ **Ask only for what the user observed or intended.** When the  " expected result "   is not user
     knowledge but an undecided **design judgment** — two screens format the same value differently,
     an unspecified empty/error state, an inconsistent notification style — do **not** ask.
     Settle it with `cc-designer:design-decision` (evidence ladder; code precedent usually ends it) and
     put the DDR in the report ' s Expected-result section as `기대 결과 (DDR-nn, 근거 Rn: …)`.
     Filing a settleable design question as  " needs designer input "   is what leaves QA findings unresolved
     across sprints.

3. **Environment information** (optional)
   - OS version
   - Device
   - App version

4. **Severity confirmation** (after presenting analysis results)
   - 🔴 Critical
   - 🟠 High
   - 🟡 Medium
   - 🟢 Low

Step 3: ZenHub Issue Creation#

## Issue Creation

Call mcp__zenhub__createGitHubIssue:

1. **Title generation**
   - Format: `[Bug] {screen_name}: {bug_summary}`
   - Crash: `[Crash] {screen_name}: {crash_situation}`

2. **Body creation** — 본문 = 계약, 서술 = 아티팩트
   - 본문에 남길 계약 블록: 재현 절차, 기대/실제 동작, 영향 범위, 심각도
   - 아티팩트로 옮길 서술: 이미지 분석 상세, 환경 덤프, 로그 전문, 원인 추정 서술
   - 서술이 20행을 넘으면 아티팩트를 **먼저** 발행해 URL을 확보한 뒤
     `## 📄 상세 기획` 링크 블록(🔒 공유 안내 포함)을 본문 앞에 붙인다
   - `Artifact` 도구가 없으면(크론·CI) 실패로 취급하지 않고 TEMPLATES.md 의
     전량 마크다운 템플릿으로 되돌린다 + `ℹ️ Artifact 미사용` 로그 한 줄
   - 규약 SoT: `cc-dev/rules/zenhub-conventions.md` → *Issue Body Artifact Contract*

3. **Label assignment**
   - `bug` (default)
   - `severity:{level}`
   - `area:{affected_area}`

4. **Pipeline movement** — 라이브 파이프라인으로만 라우팅 (`Triage`/`Backlog` 컬럼은 존재하지 않음; 이름은 `getWorkspacePipelinesAndRepositories` 로 검증)
   - Critical → In Progress (즉시 착수)
   - High → New Issues (트리아지 대기)
   - Medium → Product Backlog
   - Low → Icebox

MCP Integration#

Action	MCP Tool	Purpose
Issue creation	`mcp__zenhub__createGitHubIssue`	Create GitHub issue
Pipeline movement	`mcp__zenhub__moveIssueToPipeline`	Manage issue status
Label lookup	`mcp__zenhub__getWorkspacePipelinesAndRepositories`	Label and pipeline info

Examples#

Basic usage (with image)#

/cc-quality:bug-report /tmp/error_screenshot.png  " Order details not showing after payment completion "

Text only#

/cc-quality:bug-report  " No response when clicking login button "

Specify severity#

/cc-quality:bug-report --severity critical  " Crash on app startup "

Specify bug type#

/cc-quality:bug-report --type ui /tmp/layout.png  " Overflow on long text "

Report only (no issue creation)#

/cc-quality:bug-report --no-create  " This is a test bug "

Output Format#

Image Analysis Result#

╔════════════════════════════════════════════════════════════════╗
║  Image Analysis Result                                         ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  🖼️ Image: /tmp/screenshot.png                                 ║
║                                                                ║
║  📍 Detected Issues:                                           ║
║    1. Error dialog displayed                                   ║
║    2.  " Network error "   message detected                         ║
║                                                                ║
║  🏷️ Suggested Classification:                                  ║
║    - Type: Function Bug                                        ║
║    - Severity: High                                            ║
║    - Area: Backend/Network                                     ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Issue Creation Complete#

╔════════════════════════════════════════════════════════════════╗
║  Bug Report Created                                            ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  📋 Issue: #123                                                ║
║  📝 Title: [Bug] Payment: Order details not displayed          ║
║                                                                ║
║  🏷️ Labels:                                                    ║
║    - bug                                                       ║
║    - severity:high                                             ║
║    - area:backend                                              ║
║                                                                ║
║  📊 Pipeline: New Issues                                       ║
║                                                                ║
║  🔗 URL: https://github.com/coco-de/kobic/issues/123           ║
║                                                                ║
║  💡 Next Steps:                                                ║
║    /cc-dev:bugfix 123  # Start fix cycle                          ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Reference Documents#

Skill: ${CLAUDE_PLUGIN_ROOT}/skills/quality:bug-report-template/SKILL.md
Reference: ${CLAUDE_PLUGIN_ROOT}/skills/quality:bug-report-template/REFERENCE.md
Templates: ${CLAUDE_PLUGIN_ROOT}/skills/quality:bug-report-template/TEMPLATES.md

Key Rules#

Image-first analysis: If an image is provided, analyze it first to understand context
User confirmation: Present analysis results for severity and bug type, then confirm with user
Structured report: Use templates to maintain consistent format
Automatic labeling: Automatically assign labels matching bug characteristics
Workflow integration: Guide to /cc-dev:bugfix after issue creation
Ask for observations, decide judgments: an unspecified "expected result" is a design decision (cc-designer:design-decision), not a question for the user — see Step 2
Reproduction leaves no residue: reproducing on a shared environment mutates it. Follow cc-quality:qa-environment-hygiene — capture the original value before mutating (CBM), log a TMR, auto-revert with verification afterwards, and never close a session with "tell me whether to revert". Attach the TMR table to the report so the issue carries what the reproduction touched.