# Common: Platform Detection and PR Lookup

Shared steps used by every workflow. Run these first.

---

## Detect Platform

```bash
git remote -v
```

Scan the push URLs for the platform host — don't assume the remote is named
`origin` (forks and multi-remote setups often use `upstream` or other names):

- Contains `github.com` → use `gh` (GitHub PR)
- Contains `gitlab` → use `glab` (GitLab MR)
- Multiple or no matches → ask the human which remote to use.

---

## Determine the Base Branch

```bash
base=$(git symbolic-ref --quiet "refs/remotes/<remote>/HEAD" 2>/dev/null | sed 's@^refs/remotes/<remote>/@@')
if [ -z "$base" ]; then
  for candidate in main master; do
    git rev-parse --verify --quiet "<remote>/$candidate" >/dev/null && base=$candidate && break
  done
fi
echo "$base"
```

If that's still empty, ask the human what the base branch is.

---

## Preflight the CLI

Confirm the relevant CLI is installed and authenticated before any write:

```bash
gh auth status     # GitHub
glab auth status   # GitLab
```

If not authenticated, stop and tell the human. Don't proceed with writes.

---

## Find the Open PR/MR for the Current Branch

GitHub:

```bash
gh pr view --json state,number,url,headRefName
```

GitLab:

```bash
glab mr view --output json
```

- **Open** → use this PR/MR number/URL for comment and merge workflows.
- **Closed/merged** → for merge workflow: check for new commits
  (`git log --oneline origin/<base>..HEAD`); otherwise stop and tell the human.
- **None** → for merge workflow: run [create-pr.md](create-pr.md), then continue.
  For comment workflows: stop — nothing to comment on.

---

## Safety Guard

Refuse to operate from the default branch — that's almost always a mistake. Ask the
human to switch to a feature branch first.

# Workflow: Create PR/MR

Create a pull request (GitHub) or merge request (GitLab) for the current branch.

Start with [common.md](common.md) (platform detection, base branch, preflight).

---

## Step 1: Check for Existing PR/MR

GitHub:
```bash
gh pr view --json state,number,url
```

GitLab:
```bash
glab mr view --output json
```

- **Open** → show the URL, stop. Don't create a duplicate.
- **Closed/merged** → check for new commits since the PR was closed:
  ```bash
  git log --oneline <remote>/<base>..HEAD
  ```
  New commits exist → proceed to create a new PR.
  No new commits → tell the human, stop.
- **None** → proceed to create.

---

## Step 2: Find a Template

Look for the repo's PR/MR template:

GitHub:
```bash
ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
ls .github/PULL_REQUEST_TEMPLATE/*.md 2>/dev/null
```

GitLab:
```bash
ls .gitlab/merge_request_templates/*.md 2>/dev/null
ls .gitlab/merge_request_template.md 2>/dev/null
```

Also check common locations:
```bash
ls docs/PULL_REQUEST_TEMPLATE.md 2>/dev/null
ls PULL_REQUEST_TEMPLATE.md 2>/dev/null
```

- **Template found** → use it. The CLI will auto-apply it in interactive mode, or
  fill each section from the commits and diff for inline mode.
- **No template** → use the fallback template at
  [default-template.md](default-template.md).

---

## Step 3: Generate Title and Body

```bash
git log --oneline <remote>/<base>..HEAD            # commit list
git log <remote>/<base>..HEAD --format='%H %s%n%b' # full commit messages
git diff --stat <remote>/<base>...HEAD             # changed files summary
```

Derive the title from the most significant conventional commit. If commits are
messy, synthesize from the diff:

```
<type>(<scope>): <description>
```

Fill the body (template sections or fallback) from the commits and diff:
- **Summary** — what and why, one or two sentences
- **Changes** — bulleted, grouped by area
- **Testing** — how it was verified (if known)
- **Checklist** — tests pass, conventional commits, docs updated
- **Linked issues** — extract `Closes #N`, `Fixes #N`, `Relates to #N` from commit
  footers

---

## Step 4: Create the PR

Show the human the selected remote, branch, generated title, and body before any write. Ask for
approval to push and create the PR/MR, or proceed if they explicitly said "just do it" up front.

Push the branch only after that approval if it is not on the remote:

```bash
git push -u <remote> <branch-name>
```

### GitHub

| Mode | Command |
|------|---------|
| Auto-fill | `gh pr create --fill` |
| Inline | `gh pr create --title "<title>" --body-file -` (body via stdin) |
| Draft | `gh pr create --draft --title "<title>" --body-file -` (body via stdin) |

### GitLab

| Mode | Command |
|------|---------|
| Auto-fill | `glab mr create --fill` |
| Inline | Invoke `glab mr create` with title and description passed as separate arguments by the active command runner. |
| Draft | Invoke `glab mr create --draft` with title and description passed as separate arguments by the active command runner. |

Default to inline with the generated body. **Never pass a multi-line body directly
in the command string** (`--body "<body>"`) — quotes, backticks, and `$` in
Markdown break shell quoting. Write the body to a temp file first, then pass it
via stdin (`gh --body-file -`). For GitLab, use the active command runner's argument array rather
than constructing a shell command; never interpolate the body through command substitution.

Use `--fill` when commits are clean and the body would be redundant. Use `--draft`
when the human signals work in progress.

After creation, show the PR/MR URL to the human. Done.

# Default PR/MR Template

Fallback body template when the repository has no `.github/PULL_REQUEST_TEMPLATE.md`
or `.gitlab/merge_request_template.md`. Fill each section from the conventional
commits and diff.

```markdown
## Summary
<!-- One or two sentences: what and why -->

## Changes
<!-- Bulleted, grouped by area. Each bullet self-contained. -->
-

## Testing
<!-- How it was verified: test commands run, manual steps, edge cases checked -->

## Checklist
- [ ] Tests pass
- [ ] Commits follow conventional format
- [ ] Documentation updated (if needed)

## Linked Issues
<!-- Closes #123, Fixes #456, Relates to #789 -->
```

# Workflow: Leave a Comment

Post a new top-level comment on the current branch's open PR/MR.

Start with [common.md](common.md) (platform detection, find the open PR/MR).

---

## Step 1: Find the Open PR/MR

Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
If none is open, stop — nothing to comment on.

---

## Step 2: Compose the Comment

Ask the human for the comment body. Accept either:

- Their exact text, or
- A draft you generate (e.g., a status update, summary, or question) that they edit.

Prefer passing the body via stdin or a temp file to avoid shell-escaping issues with
quotes, backticks, or `$` in the message:

```bash
gh pr comment <number> --body-file -
glab mr note <iid> --message-file -   # if supported; otherwise --message
```

---

## Step 3: Confirm and Post

**Show the human the final comment text and target PR/MR. Ask for confirmation
before running the write command.**

### GitHub
```bash
gh pr comment <number> --body "<body>"
```
Or via stdin to avoid escaping:
```bash
echo "$body" | gh pr comment <number> --body-file -
```

### GitLab
```bash
glab mr note <iid> --message "<body>"
```

After posting, show the human the comment URL or the updated PR/MR URL. Done. Do not
merge or make further changes unless the human asks for another workflow.

# Workflow: Merge PR/MR

Merge the current branch's open PR/MR after confirming CI is green.

Defaults: **squash merge + delete the source branch**. If CI is pending, abort and
report — don't block waiting unless the human says otherwise.

Start with [common.md](common.md) (platform detection, base branch, preflight).

---

## Step 1: Find or Create the Open PR/MR

Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).

- **Open** → continue to Step 2.
- **None** → run [create-pr.md](create-pr.md) first, then continue.
- **Closed/merged** → check for new commits since it was closed
  (`git log --oneline origin/<base>..HEAD`); stop if none.

---

## Step 2: Check CI Is Green

### GitHub
```bash
gh pr checks <number>            # all checks
gh pr checks <number> --required # the merge gate
```
Exit codes for `--required`: 0 = all required checks pass; non-zero includes the
pending case (exit 8). Use `gh pr checks <number> --watch` to wait if the human
asks for it.

`--required` only shows required checks. If the full run shows failing **optional**
checks (lint, coverage, etc.), warn the human before proceeding — don't silently
ignore them.

### GitLab
```bash
glab ci status
# or
glab pipeline status
```

If any required check is **pending**, offer auto-merge instead of a direct merge:
`gh pr merge --auto` (GitHub) or `glab mr merge --auto-merge` (GitLab) queues the
merge to run once checks pass. A bare `gh pr merge` fails while required checks
are pending — "merge anyway" does not work in that state. Note: `glab mr merge`
enables auto-merge by default while a pipeline is running.

If any required check is **failing**, stop and report the status to the human.
Don't merge on red. If the human says "merge anyway": on GitHub a forced merge
requires `--admin` (bypasses branch protection, needs admin rights on the repo) —
state that implication explicitly before using it. On GitLab, merging on red is
controlled by project settings — ask the human to fix the pipeline or adjust the
setting.

---

## Step 3: Confirm Before Merging

**Show the human:**
- PR/MR URL and number/iid
- CI status (green/red)
- Merge strategy (squash by default)
- Whether the source branch will be deleted

Ask for explicit confirmation before running the merge command.

---

## Step 4: Merge

### GitHub
```bash
gh pr merge <number> --squash --delete-branch --match-head-commit <approved-head-sha>
```
Alternatives: `--rebase`, `--merge`, `--auto` (merge automatically once required
checks pass), or `--admin` (forced merge — see Step 2) per the human's request.

### GitLab
```bash
glab mr merge <iid> --squash --remove-source-branch --sha <approved-head-sha>
```
Alternatives: `--rebase`, or `--auto-merge` (merge once the pipeline succeeds —
already the default while a pipeline is running) per the human's request.

---

## Step 5: Report

Show the human the merge result — the merge commit SHA, the target branch tip, and
whether the source branch was deleted. Suggest switching back to the base branch
locally (`git checkout <base> && git pull`) if the source branch was removed. Done.

# Workflow: Read Comments

List comments on the current branch's open PR/MR.

Start with [common.md](common.md) (platform detection, find the open PR/MR).

---

## Step 1: Find the Open PR/MR

Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
If none is open, stop — nothing to read.

---

## Step 2: List Comments

### GitHub

Top-level comments:

```bash
gh pr view <number> --json comments --jq '.comments[] | {author: .author.login, body: .body, createdAt: .createdAt}'
```

Inline review comments (file/line threads) — `--json comments` does NOT include
them, so fetch them separately:

```bash
gh api --paginate repos/<owner>/<repo>/pulls/<number>/comments
```

Or, for a readable summary of top-level comments:

```bash
gh pr view <number> --comments
```

### GitLab

```bash
glab mr note list <iid>
```

This covers both top-level notes and review-thread replies — `glab` has no
separate `mr discussion` command.

---

## Step 3: Present to the Human

Show each comment with:

- **Author** (handle)
- **Body** (full text, or first few lines if long)
- **Created at** (timestamp)
- **Type** (top-level note vs. inline review comment, if distinguishable)
- **File/line** (for inline review comments)

Newest first. Group inline review comments by file/line, and threads by their
parent comment. Don't post anything — this is read-only.

# Workflow: Respond to a Comment

Post a new comment that references an existing comment on the current branch's PR/MR.

This workflow uses **simple reference replies** — a new top-level comment that quotes
the original — rather than platform-native threaded replies. True threaded replies
require GraphQL/REST calls and are a possible future enhancement.

Start with [common.md](common.md) (platform detection, find the open PR/MR).

---

## Step 1: Find the Open PR/MR and Read Comments

Run [common.md](common.md) to find the open PR/MR, then
[read-comments.md](read-comments.md) to list the comments.

---

## Step 2: Pick the Target Comment

Ask the human which comment to respond to. Accept any of:

- The comment's number/position in the list above
- The author's handle
- A snippet of the comment text

Confirm the target before composing the reply.

---

## Step 3: Compose the Reference Reply

Ask the human for the response body, then compose a top-level comment in this form:

```
Re: @<author>'s comment — <quoted snippet>

<response body>
```

Quote only the relevant few words of the original — don't reproduce the entire
comment. Keep the quote accurate and attributed.

---

## Step 4: Confirm and Post

**Show the human the composed reply and the target PR/MR. Ask for confirmation
before running the write command.**

Use the same CLI commands as [leave-comment.md](leave-comment.md#step-3-confirm-and-post)
to post the reply as a new top-level note.

### GitHub
```bash
gh pr comment <number> --body "<composed reply>"
```

### GitLab
```bash
glab mr note <iid> --message "<composed reply>"
```

After posting, show the human the comment URL or the updated PR/MR URL. Done. Do not
delete or edit the original comment — this skill create/posts only.