gihwan-dev/create-mr

Create MR

Create a properly typed, template-adherent merge request or pull request.

Success Criteria

This skill succeeds when ALL of the following are true:

1. MR/PR is created on the remote platform (GitLab or GitHub).
2. The MR URL is returned to the user as a clickable markdown link.
3. The MR body follows the project template (or fallback template if none exists).

If the skill cannot reach step 7 (MR creation), it must report the specific blocker and the exact command that failed, so the user can resolve it.

Workflow

0. Pre-flight Check

Run all checks in parallel before proceeding. If any check fails, report the specific blocker and stop.

# Run these in parallel
git branch --show-current          # Must not be main/master
git diff --cached --stat           # Warn if staged but uncommitted changes exist
git status --porcelain             # Warn if untracked/unstaged changes exist
git log @{upstream}..HEAD --oneline 2>/dev/null  # Must have commits ahead of upstream

| Check | Blocker action | |-------|---------------| | On main/master | Ask user to create a feature branch first | | No commits ahead of upstream | Nothing to create an MR for — stop | | Uncommitted changes exist | Warn user; ask whether to continue or commit first |

If git log @{upstream}..HEAD fails (no upstream set), fall back to git log origin/main..HEAD or git log origin/master..HEAD. No upstream is not a blocker — it means the branch hasn't been pushed yet, which step 7 handles.

Detect the platform once and reuse throughout:

• .gitlab-ci.yml exists or remote URL contains gitlab → GitLab (glab)
• Otherwise → GitHub (gh)

Verify CLI authentication before proceeding:

# GitLab
glab auth status 2>&1

# GitHub
gh auth status 2>&1

If auth fails, report the exact error and stop — do not attempt MR creation without auth.

Determine <base> branch: check upstream tracking branch, or fall back to main/master.

1. Classify MR Type

Analyze the diff to determine the primary change type before writing anything.

git log <base>...HEAD --oneline
git diff <base>...HEAD --stat
git diff <base>...HEAD

| Type | Signal | |------|--------| | feature | New user-facing functionality | | fix | Bug correction | | refactor | Code restructure, no behavior change | | chore | Tooling, config, deps, CI/CD | | docs | Documentation only | | perf | Performance improvement | | test | Test addition/modification only | | hotfix | Urgent production fix |

If multiple types, choose the dominant one and note secondary concerns in the body.

2. Find and Apply MR Template (MANDATORY)

Never skip this step. Always search for templates before writing the MR body.

1. Search these paths in the target repo:
   • .gitlab/merge_request_templates/
   • .github/PULL_REQUEST_TEMPLATE/
   • .github/PULL_REQUEST_TEMPLATE.md
   • .github/pull_request_template.md
   • docs/mr_templates/
2. Also run a glob search: **/*{merge_request,pull_request,PULL_REQUEST,mr_template}*
3. If multiple templates exist, pick the one matching the MR type (e.g. feature.md for features).
4. Template found → read it, fill every section. Mark inapplicable sections "N/A" with reason.
5. No template found → use the fallback below and inform the user.

3. Gather Context

git branch --show-current
git rev-parse --abbrev-ref @{upstream} 2>/dev/null
git status

Warn the user if unstaged changes or untracked files exist.

4. UI 변경 시 Before/After 스크린샷

If the diff touches UI code (components, styles, layouts, templates, CSS, HTML), capture Before/After screenshots and attach them to the MR body.

Detect UI changes:

git diff <base>...HEAD --name-only | grep -iE '\.(tsx|jsx|vue|svelte|html|css|scss|sass|less|styled)\b'

환경 확인 후 분기:

1. npx playwright --version 성공 and dev server 기동 가능 → Playwright로 스크린샷 촬영:

   git worktree add /tmp/mr-before <base>
   # install deps & start dev server in /tmp/mr-before, then:
   npx playwright screenshot --wait-for-timeout=3000 <target-url> /tmp/mr-before-screenshot.png
   git worktree remove /tmp/mr-before
   # After screenshot from current branch:
   npx playwright screenshot --wait-for-timeout=3000 <target-url> /tmp/mr-after-screenshot.png
   

2. Playwright 미설치 또는 dev server 기동 불가 → 스크린샷을 건너뛰고 MR 본문의 Before/After 섹션에 다음을 기재:

   > ⚠️ Playwright 미설치 또는 dev server 기동 불가로 자동 스크린샷을 생략합니다.
   > 수동으로 스크린샷을 추가해 주세요.
   

스크린샷 촬영 실패가 MR 생성 자체를 막지 않는다.

5. Find Related Issue

반드시 관련 이슈를 검색해서 찾는다. 브랜치명 추측에 의존하지 않는다.

5-1. 이슈 번호 힌트 수집

# 브랜치명에서 힌트 추출
git branch --show-current
# 커밋 메시지에서 힌트 추출
git log <base>...HEAD --oneline

5-2. 이슈 검색

플랫폼에 맞는 CLI로 이슈를 직접 검색한다.

GitLab:

# 키워드로 검색 (MR의 핵심 주제/기능명 사용)
glab issue list --search "<키워드>" --per-page 10
# 브랜치명에서 번호가 추출되면 해당 이슈 확인
glab issue view <번호>
# 본인에게 할당된 열린 이슈도 확인
glab issue list --assignee=@me --per-page 10

GitHub:

gh issue list --search "<키워드>" --limit 10
gh issue view <번호>
gh issue list --assignee=@me --limit 10

5-3. 이슈 매칭 및 삽입

1. 검색 결과에서 MR 변경 내용과 가장 관련 있는 이슈를 선택한다.
2. 매칭된 이슈가 있으면 MR 본문의 Related Issues 섹션에 Closes #번호를 삽입한다.
3. 후보가 여러 개이면 사용자에게 어떤 이슈를 연결할지 확인한다.
4. 관련 이슈를 찾지 못하면 Related Issues 섹션에 "None found"를 기재하고 MR 생성을 계속 진행한다. 이슈 미발견이 MR 생성을 막지 않는다.

6. Preview and Confirm

MR을 실제로 생성하기 전에 아래 고정 형식으로 사용자에게 보여주고 확인을 받는다. 코드블록이 아닌 마크다운 테이블과 본문 블록으로 표시하여 가독성을 확보한다.

## MR Preview

| 항목 | 값 |
|------|-----|
| **Title** | <type>(<scope>): <description> |
| **Type** | feature / fix / refactor / ... |
| **Source** | <현재 브랜치> |
| **Target** | <base 브랜치> |
| **Related Issue** | Closes #번호 또는 None found |
| **Commits** | <커밋 수>개 |

### Body

<MR 본문 전체 — 마크다운 렌더링 상태로>

사용자가 수정을 요청하면 해당 부분만 반영한 뒤 다시 프리뷰를 보여준다. "확인", "LGTM", "ㅇㅇ", "진행해" 등 긍정 응답을 받은 뒤에만 다음 단계로 진행한다.

스케줄/자동 실행 시: 사용자가 부재하여 확인을 받을 수 없을 때는 프리뷰를 출력만 하고 즉시 Step 7로 진행한다. 자동 실행 여부는 세션 컨텍스트의 scheduled-task 태그 또는 "자동 실행" 키워드로 판단한다.

프리뷰 후 사용자 응답 판정 기준:

• 긍정: "확인", "LGTM", "ㅇㅇ", "진행해", "ok", "네", "좋아", "생성해", "만들어" → Step 7로 진행
• 수정 요청: 제목/본문/이슈 등 특정 항목 변경 지시 → 해당 부분만 수정 후 프리뷰 재출력
• 거부: "취소", "멈춰", "그만" → MR 생성 중단, 사용자에게 알림

7. Create the MR

1. Push the branch if needed: git push -u origin <branch>.
2. Create with composed title and body using the detected platform CLI. HEREDOC으로 body를 전달하여 서식을 보존한다:

   # GitLab
   glab mr create --title "<title>" --description "$(cat <<'EOF'
   <body>
   EOF
   )" --target-branch <base>
   
   # GitHub
   gh pr create --title "<title>" --body "$(cat <<'EOF'
   <body>
   EOF
   )"
   

3. CLI 출력에서 MR/PR URL을 파싱한다.
4. URL을 클릭 가능한 마크다운 링크로 사용자에게 반환한다: [MR !번호](URL) 또는 [PR #번호](URL).
5. CLI가 에러를 반환하면 에러 메시지를 그대로 보여주고, 흔한 원인(권한 부족, 중복 MR, 타겟 브랜치 미존재)을 안내한다.

MR 생성 후 검증: CLI 출력에 URL이 포함되어 있는지 확인한다. URL이 없으면 glab mr list --source-branch <branch> 또는 gh pr list --head <branch>로 생성된 MR을 조회하여 URL을 가져온다.

MR Title

Format: <type>(<scope>): <Korean description> — under 70 chars, no emoji.

• scope는 변경된 파일의 최상위 디렉토리 또는 모듈명에서 추출한다 (예: auth, api, core).
• 파일이 여러 모듈에 걸치면 가장 많이 변경된 모듈을 scope로 사용한다.
• scope를 특정할 수 없으면 생략하여 <type>: <description> 형태로 쓴다.

Examples:

• feat(auth): 소셜 로그인 연동 추가
• fix(api): 페이지네이션 오프셋 계산 오류 수정
• refactor(core): 에러 핸들링 구조 단순화

Fallback Template

Use when no project template is found:

## Summary
<!-- what and why, 1-3 bullets -->

## Type
<!-- feature | fix | refactor | chore | docs | perf | test | hotfix -->

## Changes
<!-- key changes, bulleted -->

## Before / After
<!-- UI 변경 시 스크린샷. UI 변경 없으면 "N/A" -->
| Before | After |
|--------|-------|
| ![before]() | ![after]() |

## Related Issues
<!-- Closes #이슈번호 형식. 여러 이슈면 각각 Closes 붙인다. 없으면 "None found" -->

## Test Plan
<!-- how these changes were tested -->

## Checklist
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated (if applicable)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Error Recovery

각 단계에서 실패 시 워크플로 전체를 중단하지 않고 복구를 시도한다.

| 실패 지점 | 복구 방법 | |-----------|----------| | git log @{upstream}..HEAD 실패 (no upstream) | git log origin/main..HEAD 또는 git log origin/master..HEAD로 재시도 | | Template glob 결과 없음 | fallback template 사용 — 블로커 아님 | | 이슈 검색 CLI 에러 | Related Issues에 "검색 실패" 기재, MR 생성 계속 | | Playwright 미설치 | Before/After에 안내 문구 삽입, MR 생성 계속 | | git push rejected | git pull --rebase 안내 후 사용자에게 재시도 요청 | | MR 생성 시 duplicate 에러 | 기존 MR URL을 조회하여 반환 |

Hard Rules

1. Never skip template search — always run the search, even when you assume none exists.
2. Never leave template sections empty — fill every section or mark "N/A" with reason.
3. Show MR type classification to the user before creating.
4. Preview the complete MR and confirm with the user before pushing or creating.
5. MR titles in Korean (except the type prefix).
6. No emoji in titles.
7. 스크린샷 실패는 블로킹하지 않는다 — Playwright 부재 또는 dev server 기동 불가 시 안내 문구를 남기고 MR 생성을 계속 진행한다.
8. 이슈 검색은 수행하되, 미발견 시 계속 진행한다 — glab issue list --search 또는 gh issue list --search로 관련 이슈를 직접 검색하고, 찾으면 Closes #이슈번호를 포함한다. 검색해도 못 찾으면 "None found"를 기재하고 MR 생성을 진행한다.
9. CLI 인증 실패 시 즉시 중단한다 — auth 에러를 사용자에게 보고하고 glab auth login 또는 gh auth login 실행을 안내한다.
10. MR 생성 후 반드시 URL을 반환한다 — 클릭 가능한 마크다운 링크 형태로, 번호와 URL을 모두 포함한다.
11. git push 실패 시 원인을 진단한다 — rejected (remote에 새 커밋 존재), permission denied (권한 부족), remote not found (원격 미설정) 등 에러 유형별로 해결 방법을 안내한다. push 실패가 발생하면 MR 생성을 시도하지 않는다.
12. 이미 동일 브랜치의 MR이 존재하면 중복 생성하지 않는다 — MR 생성 전에 glab mr list --source-branch <branch> 또는 gh pr list --head <branch>로 기존 MR을 확인한다. 열린 MR이 있으면 URL을 보여주고 "이미 MR이 존재합니다. 업데이트하시겠습니까?"로 사용자에게 확인한다.