gh-search-prs

What this skill does

# GitHub CLI: Search Pull Requests

## Overview

Search for pull requests **across GitHub repositories** using `gh search prs`. Includes PR-specific filters like draft status, merge state, review status, and CI checks.

## ⚠️ CRITICAL: Search vs List Commands

**`gh search prs`** - GitHub-wide search (THIS SKILL):
- Searches across **multiple repositories** or organizations
- Searches in **specific repos outside your current directory**
- Uses GitHub's search query syntax with qualifiers
- Examples: "Find draft PRs in kubernetes repos", "Search for approved PRs in microsoft org"

**`gh pr list`** - Current repository only (NOT THIS SKILL):
- Lists PRs in **your current working directory's repo**
- Uses simple flag-based filtering
- Examples: "Show my PRs in this repo", "List open PRs here"

**When user says "my PRs" or "PRs here" → Use `gh pr list` (NOT this skill)**
**When user specifies repo/org or cross-repo search → Use `gh search prs` (THIS skill)**

## When to Use This Skill

Use this skill when the user explicitly indicates:
- Searching across **multiple repositories or organizations**
- Searching in a **specific repo** (e.g., "in kubernetes/kubernetes")
- Cross-GitHub searches (e.g., "all draft PRs across the organization")
- Complex queries needing search qualifiers (e.g., "approved PRs with >10 comments in golang repos")

**DO NOT use this skill when:**
- User asks about "PRs in this repo" or "my PRs here"
- No repo/org is specified and context is clearly current repository
- Use `gh pr list` for current repo operations instead

## Syntax

```bash
gh search prs [<query>] [flags]
```

## Key Flags Reference

### PR-Specific Filters

| Flag | Purpose | Example |
|------|---------|---------|
| `--draft` | Filter draft PRs | `--draft` |
| `--merged` | Filter merged PRs | `--merged` |
| `--merged-at <date>` | Merged at date | `--merged-at ">2024-01-01"` |
| `-B, --base <string>` | Base branch name | `--base main` |
| `-H, --head <string>` | Head branch name | `--head feature-auth` |
| `--review <string>` | Review status | `--review approved` |
| `--review-requested <user>` | Review requested from | `--review-requested @me` |
| `--reviewed-by <user>` | Reviewed by user | `--reviewed-by octocat` |
| `--checks <string>` | CI check status | `--checks success` |

### User Filters

| Flag | Purpose | Example |
|------|---------|---------|
| `--author <string>` | Created by user | `--author octocat` |
| `--assignee <string>` | Assigned to user | `--assignee @me` |
| `--mentions <user>` | Mentions specific user | `--mentions octocat` |
| `--commenter <user>` | Commented by user | `--commenter octocat` |
| `--team-mentions <string>` | Mentions team | `--team-mentions myteam` |

### PR Attributes

| Flag | Purpose | Example |
|------|---------|---------|
| `--label <strings>` | Has specific labels | `--label bug,urgent` |
| `--state <string>` | PR state: open or closed | `--state open` |
| `--milestone <title>` | In specific milestone | `--milestone v1.0` |
| `--locked` | Locked conversation | `--locked` |
| `--no-label` | Has no labels | `--no-label` |

### Repository Filters

| Flag | Purpose | Example |
|------|---------|---------|
| `--owner <strings>` | Repository owner | `--owner github` |
| `-R, --repo <strings>` | Specific repository | `--repo cli/cli` |
| `--language <string>` | Repository language | `--language typescript` |
| `--visibility <strings>` | Repo visibility | `--visibility public` |
| `--archived` | In archived repos | `--archived` |

### Engagement Metrics

| Flag | Purpose | Example |
|------|---------|---------|
| `--comments <number>` | Number of comments | `--comments ">5"` |
| `--reactions <number>` | Reaction count | `--reactions ">10"` |
| `--interactions <number>` | Comments + reactions | `--interactions ">15"` |

### Date Filters

| Flag | Purpose | Example |
|------|---------|---------|
| `--created <date>` | Creation date | `--created ">2024-01-01"` |
| `--updated <date>` | Last update date | `--updated ">2024-06-01"` |
| `--closed <date>` | Close date | `--closed "<2024-12-31"` |

### Search Scope

| Flag | Purpose | Example |
|------|---------|---------|
| `--match <strings>` | Search in: title, body, comments | `--match title` |

### Output & Sorting

| Flag | Purpose | Example |
|------|---------|---------|
| `-L, --limit <int>` | Max results (default: 30) | `--limit 100` |
| `--sort <string>` | Sort by: comments, created, reactions, etc. | `--sort updated` |
| `--order <string>` | Sort direction: asc or desc | `--order desc` |
| `--json <fields>` | JSON output | `--json number,title,state,isDraft` |
| `-w, --web` | Open in browser | `-w` |

## JSON Output Fields

`assignees`, `author`, `authorAssociation`, `body`, `closedAt`, `commentsCount`, `createdAt`, `id`, `isDraft`, `isLocked`, `isPullRequest`, `labels`, `number`, `repository`, `state`, `title`, `updatedAt`, `url`

## Exclusion Syntax (Critical!)

When using inline query exclusions (negations with `-`), you MUST use the `--` separator:

✅ Correct: `gh search prs -- "search-terms -qualifier:value"`
❌ Wrong: `gh search prs "search-terms" --flag=-value`
❌ Wrong: `gh search prs "search-terms" --flag=!value`
❌ Wrong: `gh search prs --label=-WIP`

**Examples:**
- `gh search prs -- "feature -label:draft"` (exclude label)
- `gh search prs -- "fix -is:draft"` (exclude draft PRs)
- `gh search prs -- "deploy -author:bot"` (exclude author)
- `gh search prs -- "security -review:changes_requested"` (exclude review status)

**Why the `--` separator is required:**
The `--` tells the shell to stop parsing flags and treat everything after it as arguments. Without it, `-qualifier:value` inside quotes may be misinterpreted.

## Critical Syntax Rules

### When to Use Flag Syntax vs Query Syntax

**Decision Tree:**
```
Does your search include:
  - Any exclusions (NOT, minus, without, except)?  → Use Query Syntax with `--`
  - Complex boolean logic (OR, AND)?              → Use Query Syntax with `--`

Otherwise:
  - Simple positive filters only?                  → Use Flag Syntax
```

**Flag Syntax** (for positive filters):
```bash
gh search prs "refactor" --draft --state open
```

**Query Syntax with `--`** (required for exclusions):
```bash
gh search prs -- "refactor -label:wip -is:draft"
```

**⚠️ NEVER mix both syntaxes in a single command!**

### 1. Exclusions and Negations

**CRITICAL:** When excluding results, you MUST use query syntax with the `--` separator.

#### Exclusion Syntax Rules:
1. Use the `--` separator before your query
2. Use `-qualifier:value` format (dash prefix for negation)
3. Quote the entire query string

#### Examples:

**Single exclusion:**
```bash
# Exclude specific label
gh search prs -- "refactor -label:wip"

# Exclude draft PRs
gh search prs -- "feature -is:draft"
```

**Multiple exclusions:**
```bash
# Exclude multiple labels
gh search prs -- "bug -label:wip -label:blocked"

# Exclude draft PRs and specific review status
gh search prs -- "security -is:draft -review:changes_requested"
```

**Combine with positive filters using flags:**
```bash
# Wrong - mixing syntaxes:
gh search prs "fix" --state open -label:wip  # ❌

# Correct - use query syntax for everything when excluding:
gh search prs -- "fix state:open -label:wip"  # ✅
```

**PowerShell exclusions:**
```powershell
# Use --% to prevent PowerShell parsing
gh --% search prs -- "refactor -label:wip"
```

#### Common Exclusion Patterns:

| User Request | Command |
|--------------|---------|
| "Find PRs but not drafts" | `gh search prs -- "feature -is:draft"` |
| "PRs excluding specific label" | `gh search prs -- "bug -label:wip"` |
| "PRs not from bot authors" | `gh search prs -- "update -author:dependabot -author:renovate"` |
| "PRs excluding failed checks" | `gh search prs -- "deploy -status:failure"` |
| "PRs not targeting main branch" | `gh search prs -- "feature -base:main"` |
| "PRs excluding review status" | `gh search prs -- "fix -review:changes_requested"` |
| "PRs not merged yet" | `g