dependabot-review

What this skill does

# Dependabot PR Review

Triage, classify, and merge open Dependabot PRs with risk-based assessment.

## Auto-Invoke Triggers

This skill activates when:

1. **Keywords**: "dependabot", "dependabot PRs", "dependency updates", "merge dependabot", "review dependabot", "dependency PRs", "bump PRs", "update dependencies"
2. **Command**: `/dependabot-review`

---

## Arguments

- *(no args)* — Triage mode: list all open Dependabot PRs with risk classification
- `--merge-safe` — Merge all PRs classified as SAFE TO MERGE (asks for target branch first)
- `--pr <number>` — Deep-dive analysis of a single Dependabot PR
- `--base <branch>` — Target branch for retargeting PRs before merge (skips the prompt)

---

## Prerequisites

- GitHub CLI (`gh`) authenticated with repo access
- Repository must have open Dependabot PRs

Verify:

```bash
gh auth status
```

---

## Workflow

### Step 1: Fetch Open Dependabot PRs

```bash
gh pr list \
  --author "app/dependabot" \
  --state open \
  --json number,title,labels,headRefName,baseRefName,mergeable,isDraft,createdAt,statusCheckRollup \
  --limit 50
```

If `--pr <number>` was provided, fetch that single PR instead:

```bash
gh pr view <number> \
  --json number,title,body,labels,headRefName,baseRefName,mergeable,isDraft,createdAt,statusCheckRollup,additions,deletions
```

If no Dependabot PRs are found, report "No open Dependabot PRs found" and stop.

### Step 2: Enrich Each PR

For each PR, gather additional data:

**Files changed** (for lockfile-only detection):

```bash
gh pr diff <number> --name-only
```

**CI status**: Extract from `statusCheckRollup` in the JSON. Classify as:
- `pass` — all checks SUCCESS or SKIPPED
- `fail` — any check FAILURE
- `pending` — any check IN_PROGRESS or QUEUED
- `none` — no checks ran

### Step 3: Classify Each PR

Apply the risk matrix to each PR:

**Parse version info from PR title:**

Dependabot titles follow: `build(deps): bump <package> from <old> to <new> in <path>`

For grouped updates: `build(deps): bump the <group> group across N directory with M updates`

**Determine semver delta:**
- Compare major versions: different → `major`
- Compare minor versions: different → `minor`
- Otherwise → `patch`
- Grouped PRs: check PR body for the update table; if any update is major → treat entire PR as `major`

**Apply classification rules:**

#### SAFE TO MERGE
All of these must be true:
- CI: `pass` (or `none` for lockfile-only changes)
- Mergeable: `MERGEABLE`
- AND one of:
  - Semver: `patch` (any dependency)
  - Semver: `minor` AND package matches known-safe pattern
  - Files changed: lockfile only (`*-lock.*`, `*.lock`, `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, `gradle.lockfile`)
  - Ecosystem: `github_actions` AND semver: `minor` or `patch`

**Known-safe patterns** (safe at minor):
- `@types/*` — TypeScript type definitions
- `eslint-*`, `prettier`, `@typescript-eslint/*` — linters/formatters
- `@testing-library/*`, `@playwright/test`, `vitest` — test tooling
- `actions/*`, `docker/*`, `hashicorp/*` — CI actions (minor only)

#### REVIEW RECOMMENDED
- CI: `pass` AND mergeable: `MERGEABLE`
- AND one of:
  - Semver: `minor` AND direct production dependency
  - Grouped PR with no major bumps
  - Package on framework watchlist (even at minor)

**Framework watchlist** (always flag for review at minor+):
- `next`, `react`, `react-dom`, `svelte`, `vue`, `angular`
- `spring-boot`, `kotlin`, `gradle`
- `supabase-js`, `@supabase/*`
- `mapbox-gl`, `framer-motion`

#### REQUIRES HUMAN REVIEW
- Any `major` semver bump
- Grouped PR containing any major bump

#### Security Override
Security-labeled PRs stay in their normal risk tier (a security patch is still SAFE, a security minor is still REVIEW, etc.) but are **always flagged with an urgency callout** at the top of the report. Security + major = HUMAN REVIEW.

#### BLOCKED
- CI: `fail` → note possible root causes (Dependabot lacks repo secrets, pre-existing failures)
- Mergeable: `CONFLICTING` → suggest `@dependabot rebase`
- Mergeable: `UNKNOWN` → suggest waiting for GitHub to compute

### Step 4: Present Triage Report

Format the report as:

```
## Dependabot PR Triage — {owner}/{repo}
{N} open PRs found

### SAFE TO MERGE ({count})
| PR | Package | From → To | Type | Scope | CI | Files |
|----|---------|-----------|------|-------|----|-------|
| #142 | eslint | 8.56 → 8.57 | patch | dev | pass | lockfile |

### REVIEW RECOMMENDED ({count})
| PR | Package | From → To | Type | Reason | CI |
|----|---------|-----------|------|--------|----|
| #140 | next | 14.1 → 14.2 | minor | framework watchlist | pass |

### REQUIRES HUMAN REVIEW ({count})
| PR | Package | From → To | Type | Reason |
|----|---------|-----------|------|--------|
| #131 | spring-boot | 3.2 → 4.0 | major | major version bump |

### BLOCKED ({count})
| PR | Package | Issue | Suggested Action |
|----|---------|-------|-----------------|
| #129 | gradle | CI fail | Check Dependabot secrets / pre-existing lint errors |
| #127 | pnpm group | conflict | `@dependabot rebase` |
```

After the report, ask the user what they want to do using natural conversation.

### Step 5: Execute Actions

**If user chooses to merge safe PRs (or `--merge-safe` flag):**

1. **Ask for target branch**: "What branch should these PRs target? (e.g., main, develop)"
   - Skip if `--base` was provided
2. **Retarget if needed**: For each PR where `baseRefName` differs from the target:
   ```bash
   gh pr edit <number> --base <target-branch>
   ```
3. **Approve and merge each safe PR**:
   ```bash
   gh pr review <number> --approve --body "Auto-approved: safe dependency update"
   gh pr merge <number> --squash
   ```
   If squash fails (repo doesn't allow squash):
   ```bash
   gh pr merge <number> --merge
   ```
   If merge commits also fail:
   ```bash
   gh pr merge <number> --rebase
   ```

**If user chooses to rebase conflicted PRs:**

```bash
gh pr comment <number> --body "@dependabot rebase"
```

**If user chooses single PR deep-dive (`--pr <number>`):**

Present:
- Package name, old version → new version
- Semver classification and risk tier
- Release notes excerpt (from PR body)
- Files changed list
- CI check details (which passed, which failed)
- Recommendation with reasoning

### Step 6: Summary

After all actions, present:

```
## Summary
- Merged: {N} PRs ({list numbers})
- Rebased: {N} PRs ({list numbers})
- Skipped: {N} PRs ({reasons})
- Remaining: {N} PRs requiring human review
```

---

## CI Failure Diagnostics

When a Dependabot PR has failing CI, check these common causes before blaming the dependency update:

1. **Missing secrets**: Dependabot PRs run with read-only `GITHUB_TOKEN` and cannot access repo Actions secrets. Only Dependabot-specific secrets (Settings > Security > Dependabot secrets) are available. Look for errors like "Missing required environment variable" or auth failures.

2. **Lockfile-only changes**: If the PR only changes lockfiles (`pnpm-lock.yaml`, `package-lock.json`, etc.), it cannot cause lint, type-check, or build failures. Flag these as pre-existing issues.

3. **Pre-existing failures**: Check if the same CI checks fail on the base branch. If so, the failure is not caused by the dependency update.

---

## Important Notes

1. **Triage is read-only by default** — no merges happen unless the user explicitly requests it or uses `--merge-safe`
2. **Always ask for target branch** before merging — never assume main or develop
3. **Grouped PRs**: Parse the update table in the PR body to identify individual packages and their semver bumps
4. **Security PRs**: Always surface these prominently regardless of semver level
5. **`@dependabot rebase`**: The preferred fix for lockfile conflicts — Dependabot regenerates the lockfile against the current base

---

## Progressive Disclosure

For more details, see:
- [WORKFLOW.md](WORKFLOW.md) — Detailed 5-phase methodology
- [EXAMPLES.md](EXAMPLES.md) — Real-world triage scenarios
- [TROUBLESHOOTING.md](T