Create MR

Use after review-code passes. A good MR description tells the reviewer what problem was solved and whether it's actually fixed — in 30 seconds or less. Don't list every file you touched. Don't over-explain. Give them the mental model they need to review well.

Pre-flight

The MR must target the branch you actually branched from — not always main. If fix-issue created your branch, that base branch was recorded automatically; resolve it before diffing or opening the MR.

RESOLVE="$HOME/.claude/skills/gitlab-config/scripts/auto_resolve_issue.py"
BRANCH=$(git branch --show-current)
BASE=$(git config --local --get branch.$BRANCH.base || echo main)

git fetch origin
git status --porcelain             # anything uncommitted?
git log origin/$BASE..HEAD --oneline       # confirm what's going in
glab pipeline status 2>/dev/null || true   # check CI

If git status --porcelain shows uncommitted changes, commit them before pushing — an MR should never leave work behind uncommitted. Follow fix-issue's commit convention (one commit per logical concern):

git add <files>
git commit -m "fix(scope): what was broken and how it's fixed

Closes #<issue-number>"

Don't commit unrelated or leftover debug changes — if something in the working tree doesn't belong in this MR, that's a signal to stop and ask, not to bundle it in.

Check the issue thread for related work first

Other people may have already posted context in the issue — a prior attempt, a linked commit, a related MR, a decision made in a comment. If your MR description doesn't mention it, reviewers re-derive context that already exists, or miss that something relevant already happened.

GITLAB="$HOME/.claude/skills/gitlab-config/scripts/gitlab_api.py"
python $GITLAB sync-issue <project> <issue_iid>   # merges into the cache — see gitlab-config

Scan the returned notes[] for: other MRs (!123, "mentioned in merge request"), commits ("mentioned in commit <sha>"), other issues, or a comment stating a decision or a prior fix attempt. If you find any, list them — this becomes the MR's "Related" section below. If there's nothing, skip that section; don't invent context.

Title

Format, always: <feature_type>: #<issue_number> <description>. The issue number is never optional — if there's no issue, that's a blocker, not a reason to drop it (see write-issue/analyze-issue).

<feature_type> matches the commit convention: feat, fix, refactor, test, chore, docs. <description> is what was fixed or added — from the user's perspective, not the implementation's.

fix: #42 users with uppercase emails can now log in
feat: #108 CSV export on the reports page

Not: fix: add .downcase to auth query (missing issue number, and describes the how, not the what). Not: fix: users with uppercase emails can now log in (missing issue number).

Description

Keep it to 3 sections, plus a 4th only if Step 1 found something. No more. Every section is bullets, not prose — a reviewer should get each section's key point in the time it takes to scan, not read.

## What and why

Closes #<issue-number>

- Problem: <what was broken or missing, from the user's perspective — not the code's>
- Fix: <what changed to solve it>
- Result: <confirms it's actually fixed, not just "should work now">

## How

- <one bullet per non-obvious decision — skip anything a reviewer would find obvious from the diff>

## Verified

- [ ] Original problem reproduced and confirmed fixed
- [ ] Tests pass
- [ ] Manually tested: <what you did to verify>

## Related
<Only if the issue thread mentioned it — one line each, skip the section entirely otherwise>
- Follows up on !<mr-number> — <why it wasn't enough / what changed>
- Prior attempt in <commit-sha> — <why this MR differs>

The Closes #<number> line goes at the top of the description so GitLab auto-links and auto-closes the issue on merge.

Create

Default to glab — create the MR directly with git, no API token required. Never use --fill — it pulls the title/description from raw commit messages and skips the structured summary the reviewer needs. Build the description from the Description template above (as real markdown — headings, the Closes # line, the checklist) and pass it explicitly:

# 1. Default — glab CLI
git push -u origin HEAD

DESCRIPTION=$(cat <<'EOF'
## What and why

Closes #<issue-number>

- Problem: <what was broken or missing>
- Fix: <what changed to solve it>
- Result: <confirms it's actually fixed>

## How

- <one bullet per non-obvious decision>

## Verified

- [x] Original problem reproduced and confirmed fixed
- [x] Tests pass
- [x] Manually tested: <what you did to verify>
EOF
)

glab mr create \
  --title "<feature_type>: #<issue-number> <what was fixed>" \
  --description "$DESCRIPTION" \
  --target-branch "$BASE" \
  --assignee @me \
  --remove-source-branch

If glab isn't installed or isn't authenticated for this instance, fall back to the API script (useful for multi-instance setups already configured in gitlab-config, or when the API token has write access but glab auth status doesn't):

# 2. Fallback — API script (supports multiple GitLab servers)
# target "auto" resolves to the branch you branched from, falling back to main
RESOLVE="$HOME/.claude/skills/gitlab-config/scripts/auto_resolve_issue.py"
git push -u origin HEAD
python $RESOLVE create-mr <project> <branch> auto \
  "<feature_type>: #<issue-number> <what was fixed>" \
  "Closes #<issue-number>

- Problem: <what was broken or missing>
- Fix: <what changed to solve it>" \
  <issue_iid>
# e.g. python $RESOLVE create-mr webapp feat/42-fix-login auto \
#   "fix: #42 users with uppercase emails can now log in" \
#   "Closes #42\n\n- Problem: login rejected uppercase emails\n- Fix: normalize email input before DB lookup" 42

If the API script also fails with a permission/scope error (403, insufficient_scope, Forbidden), that confirms the token lacks write access — don't retry it, drop back to glab (step 1). If neither glab nor the API script works, fall back to manual:

# 3. Last resort — no glab, no working API token (manual)
git push -u origin HEAD
# Open the URL GitLab prints, paste the markdown description above

After creating — comment on the issue (required)

Creating the MR is not the last step. Every MR must be followed by a comment on its issue, on every creation path (glab, API script, or manual). Do this before reporting back; if you can't post it, say so plainly instead of calling the work done.

The comment is a brief for someone who will never open the MR: did the issue's goal land, and what are the key numbers. A bare Fixed in !123: <url> is not acceptable. GitLab renders an MR URL as !123, so that reads Fixed in !123: !123 and says nothing. Name the MR once, as !<mr-number> (GitLab links it), never both forms.

**Merge request:** !<mr-number> → `<target-branch>` — open, awaiting review

**Goal:** <the outcome the issue asked for, in one sentence from the user's view>
- <key result or metric: what a user can now do, records affected, time before → after>
- <edge case now handled, or tests added>
- Checks: <n>/<n> passed ✅

Rules:

• 2-4 bullets, one fact each, readable in 10 seconds. Lead with the outcome and the numbers, not the process.
• No file names, class names, commands, or commit lists. How it was done belongs in the MR description.
• Only claim what you verified. Unverified or blocked: replace Goal with Blocked on: and add a bold Needs: line for the human action.
• A query or payload fix may carry one before → after line (e.g. 8.2s → 0.3s), not the full statements; those stay in the MR.
• Don't post a second comment if the issue already has one for this MR; update your own instead.

# Via glab
glab issue note <issue-number> --message "$NOTE"

# Via API (any instance)
GITLAB="$HOME/.claude/skills/gitlab-config/scripts/gitlab_api.py"
python $GITLAB post-issue-comment <project> <issue_iid> "$NOTE"

Then tell the user the MR URL and that the issue comment was posted, in one line each. For a longer recap after merge, use summarize-issue, which follows the same shape.