merge-briefing

Files (1)

• SKILL.md

SKILL.md (first lines)

# merge-briefing

## Overview

A merge is irreversible shared state, so it is gated on the user's explicit
per-PR answer. The gate is cheap to satisfy formally and easy to satisfy
falsely: the honest version needs a probe wide enough to support "nothing is
open", and the surface where blocking findings actually live — inline review
threads — is the one a natural-looking `gh pr view --json comments,reviews`
call silently omits.

This skill is the on-demand home for that procedure. The *Pre-Merge Reporting*
rule ([`ETHOS.md` → Rules praxis carries](../../ETHOS.md#rules-praxis-carries))
keeps the gate; the six-part list in Step 4 below is the report's shape; the
steps below are how you get from "the PR looks done" to a question the user
can answer in one word.

**Core principle:** the briefing is a claim about the PR's state, so every line
in it is probed at compose time — not recalled from when the PR was opened.

## When to Use

- About to ask the user to approve a merge.
- A merge was requested and you have not yet surfaced a briefing this turn.
- Re-asking after a previous ask went unanswered, or after CI/review moved.
- A companion, follow-up, or regenerated PR is next in a cluster the user
  already approved once.

## The Iron Law

- **One PR, one briefing, one answer.** Approving PR X approves only X. The
  one exception is the [bulk merge](#bulk-merge-several-prs-one-answer): one
  turn with a separate briefing section per PR, one ask that lists them, and
  an answer that approves the listed set.
- **Compose the briefing from this turn's probe output.** An entry-time `CLEAN`
  status is not permanent; a stale anchor makes the user discover a conflict
  you should have caught.
- **Never merge on a progress signal.** "계속", "ok", "진행" move work forward;
  they are not consent for a shared-state mutation.

## Process

### Step 1: Probe all three surfaces

Findings live on three surfaces and no single command covers them. Run all
three before writing a word of the briefing.

```bash
# 1 — CI
gh pr checks <N> --repo <owner>/<repo>

# 2 — conversation timeline + review bodies + mergeability + pushed HEAD
gh pr view <N> --repo <owner>/<repo> \
  --json mergeable,mergeStateStatus,isDraft,headRefOid,reviews,comments
```

```bash
# 3 — inline review threads (the surface #2 does NOT include)
gh api graphql --paginate -f query='
query($owner:String!, $repo:String!, $pr:Int!, $endCursor:String) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      reviewThreads(first:100, after:$endCursor) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id isResolved isOutdated path line
          comments(first:1) { nodes { author { login } body } }
        }
      }
    }
  }
}' -F owner=<owner> -F repo=<repo> -F pr=<N> \
  --jq '.data.repository.pullRequest.reviewThreads.nodes[]
        | select(.isResolved | not)
        | {id, path, line, author: .comments.nodes[0].author.login,
           body: .comments.nodes[0].body}'
```

`body` is in the projection because the label is in the thread's own text, and
the label is what Step 2 grades on. `--paginate` with `$endCursor` is not
decoration — a PR two bots have worked over passes 100 threads, and a single
page silently drops the rest, which then reads as "no open threads".

**Surface #2 truncates at 100 as well, and silently.** `gh pr view --json
comments,reviews` issues `comments(first: 100)` / `reviews(first: 100)` with no
cursor variable, so on a PR past either count the tail is simply absent. When
one of them is at 100 rows, re-collect that surface through the paginated REST
endpoint before grading:

```bash
gh api repos/<owner>/<repo>/pulls/<N>/reviews --paginate -q '.[] | {user: .user.login, state, body}'
gh api repos/<owner>/<repo>/issues/<N>/comments --paginate -q '.[] | {user: .user.login, body}'
```

**An empty result is not yet an answer.** It means "no open threads" and "the
query is wrong" at the same time until you have seen this exact query print
rows on a PR known to have them. Run it once against such a PR; that is the
positive control the negative claim rests on.

In a fork clone, `--repo` must name the fork on every probe: a bare `gh pr`
call resolves against the parent repo (see `worktree-merge-cleanup` →
*Pre-call checklist*).

If CI is pending or failing, **stop here** — do not ask yet. A briefing whose
verification rows are still moving is asking the user to approve a guess.

**Read which commit each human approval covers** before writing "approved":
`reviewDecision: APPROVED` survives later pushes. Group the reviews by
reviewer and take each one's **latest** `APPROVED` review (an earlier approval
is superseded by a re-approval; a later `CHANGES_REQUESTED` or `DISMISSED`
from the same reviewer means no current approval). Compare that review's
`commit_id` with `headRefOid` and list the non-merge commits after it
(`git log --no-merges <commit_id>..<head>`) in part 5 as "not reviewed by
<human>" (see the Failure Modes row for the command).

**The merge state is an allowlist, not a "not obviously broken" check.** Ask
only when `mergeable` is `MERGEABLE` **and** `mergeStateStatus` is `CLEAN` or
`HAS_HOOKS` — those two are the only values that mean mergeable with a passing
commit status. Every other value stops the ask and names itself in the briefing:

From devseunggwan/praxis, MIT.

More from devseunggwan/praxis