pr

Files (1)

• SKILL.md

SKILL.md (first lines)

# pr

Create a pull request. **Fast, good defaults, operator confirms before anything is created.**

The defining design principles:

> **PR early.** Open the PR after the first commit, not when the branch is "done." A PR with one commit signals "work started" and gives the team visibility. Subsequent commits show up as reviewable increments in the GitHub UI — the author can self-review from the mobile app between sessions, and teammates see progress without needing CLI access. PRs are cheap; delayed visibility is expensive.
>
> **DX-first.** Derive as much as possible automatically — base branch, title, body. The operator should need to type as little as possible.
>
> **Pitch before creating.** Always show the full draft in chat and get explicit approval. Never run `gh pr create` without confirmation.
>
> **Smart base for stacked PRs.** If the branch was cut from another feature branch (not main), use that branch as the base. Merging a stacked PR into main loses the stack structure.

## Phase 1 — Gather context

Run in parallel:

- **Branch:** `git branch --show-current`
- **Commits on branch:** `git log --oneline main..HEAD` (or `git log --oneline HEAD ^origin/main` if on remote)
- **Push state:** `git status -sb` — is the branch already pushed to origin?
- **Remote default branch:** read the file from GitHub (e.g. `get_file_contents`) or list branches (e.g. `list_branches`) to determine the default branch — don't hardcode `main`
- **Repo merge conventions:** Read `AGENTS.md` and `CONTRIBUTING.md` at the repo root (if they exist) for merge strategy guidance — e.g. squash vs merge commit, stack handling, branch cleanup. Store any findings for use in Phase 6.
- **Repo config:** Check for `.github-settings.yaml` at the repo root (see Phase 1.1 below).

Extract a ticket ID from the branch name if present (e.g. `vidbina/vid-123-some-slug` → `VID-123`). If found, fetch the Linear issue (`get_issue`) for title and description.

### Rename the session

After context is gathered, rename the session so the user can identify it at a glance (e.g. in a terminal tab). A good name includes the ticket number and a 2–4 word summary — e.g. "VID-662 rename titles (pr)".

If a tool or command is available to rename the session programmatically, use it. Otherwise, suggest the user rename it — but don't block on this. Move on to drafting either way.

### Phase 1.1 — Repo config check

Check for `.github-settings.yaml` at the repo root. This file declares the repo's intended GitHub settings so the skill can detect drift and guide first-time setup.

**If `.github-settings.yaml` exists:**

Read it and store the declared settings for use in Phase 6 (merge strategy). Compare against what's observable from the GitHub API (e.g. allowed merge methods by querying repository settings from GitHub (e.g. `search_repositories`)). If a mismatch is detected, surface it as a warning in the Phase 4 pitch:

```
⚠️  Repo config drift detected:
  .github-settings.yaml says: default_method = "squash", squash_title = "pr_title"
  GitHub API says: squash merging is disabled
  → Fix in GitHub Settings > Pull Requests, or update .github-settings.yaml
```

Do not block on drift — warn and continue. The operator decides whether to fix it now or later.

**If `.github-settings.yaml` does not exist (first PR in an unconfigured repo):**

Surface a one-time setup prompt after the PR is created (Phase 5), not before — don't gate PR creation on repo config:

```
📋 This repo has no .github-settings.yaml. Want to set one up?
   This declares your merge mode, squash-merge title format, and branch protection
   expectations so the /pr skill can detect drift.

   (a) Generate from current GitHub settings — I'll read the API and draft it
   (b) Copy the template — you'll customize manually
   (c) Skip — not now
```

On (a): read the repo's current settings via the GitHub API and draft a `.github-settings.yaml` — but validate every generated value against the KB template's norm levels before presenting (read `templates/github-settings.yaml` via the `./kb` or `./knowledge-base` symlink if present; otherwise fall back to the schema reference below). **Never launder a live footgun into the spec:** for fields the KB template marks REQUIRED (`squash_title: pr_title`, `squash_message: commit_messages`), write the norm value into the generated file regardless of what the live setting says, and flag the live deviation as drift with a ready-to-run `gh` fix command (HITL guardrail below). Only PREFERENCE fields adopt live values. Generate-from-live without this validation turns a misconfigured repo into a "compliant" spec — that's how GitHub's title-source footgun got written into a downstream repo's spec, and `/align` then had no basis to flag it. On (b): point to `templates/github-settings.yaml` in the kb repo. On (c): skip silently. Don't ask again in the same session.

**Schema reference (`templates/github-settings.yaml`):**

```yaml
merge:
  allowed_methods: [merge, squash, rebase]   # PREFERENCE
  default_method: squash                     # PREFERENCE
  squash_title: pr_title                     # REQUIRED
  squash_message: commit_messages            # REQUIRED
  delete_branch_on_merge: true               # PREFERENCE

branch_protection:                           # PREFERENCE (all fields)
  default_branch: main
  require_pr_reviews: true
  require_status_checks: true
```

Norm levels: **REQUIRED** fields are binding org norms — the declared value is the only valid one. Drift in live settings gets fixed live (surface the `gh` command), never adopted into the spec; a spec that matches a misconfigured reality is not compliant. **PREFERENCE** fields are repo-level choices.

Fields:
- `merge.allowed_methods` — which merge buttons are enabled on GitHub
- `merge.default_method` — which method is selected by default
- `merge.squash_title` — squash-merge commit title source: `"pr_title"` (REQUIRED) — GitHub's `"commit_message"` factory default uses the head commit's subject for single-commit PRs, silently dropping the `[TICKET-ID]` from git log
- `merge.squash_message` — squash-merge commit message (body) source: `"commit_messages"` (REQUIRED) — keeps `Co-authored-by`/`Assisted-by` provenance trailers from individual commits in the squash commit body
- `merge.delete_branch_on_merge` — auto-delete head branch after merge
- `branch_protection.default_branch` — the branch protection rules apply to
- `branch_protection.require_pr_reviews` — require PR review before merge
- `branch_protection.require_status_checks` — require CI to pass before merge

**HITL guardrail:** Repo-level changes (merge mode, branch protection) affect all contributors and cannot be scoped to a single PR. The skill handles these in three tiers:

1. **Default: suggest with `gh` CLI commands.** Present the drift finding and offer ready-to-run `gh` commands so the operator can copy-paste:
   ```
   ⚠️  Squash-merge title source is "commit_message" (GitHub default footgun).
       Expected: "pr_title" per .github-settings.yaml

   Fix:
     gh api repos/{owner}/{repo} -X PATCH -f squash_merge_commit_title=PR_TITLE
   ```
2. **On operator request: run the commands directly.** If the operator says "go ahead" or "fix it", the skill executes the `gh` commands itself. Confirm with the user to gate — never auto-fix drift without explicit approval.
3. **Never silently modify.** Even in yolo mode, repo settings changes require an explicit gate. These are org-wide side effects, not branch-scoped changes.

## Phase 2 — Detect base branch

Find the correct base using this algorithm:

```bash
# All local branches that are ancestors of HEAD, ranked by closeness
git for-each-ref --format='%(refname:short)' refs/heads/ \
  | grep -v "$(git branch --show-current)" \
  | while read b; do
      if git merge-base --is-ancestor "$b" HEAD 2>/dev/null; then
        count=$(git log --oneline "$b"..HEAD | wc -l | tr -d ' ')
        echo "$count $b"

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb