--- name: audit-deps description: > Audit open dependabot PRs in this repo. Spawns one investigator per PR (each with a codebase-walk sub-agent), produces a comparison table with per-PR risk + recommendation, and proposes a merge order that minimizes rebase churn. Audit-only — stops at recommendations; user authorizes execution. Use when dependabot has stacked up multiple open PRs and you want a structured pass before merging. allowed-tools: Bash, Read, Glob, Grep, WebFetch, WebSearch, Agent, TaskCreate, TaskUpdate, TaskList, AskUserQuestion argument-hint: "[pr-number ...] (optional, defaults to all open dependabot PRs)" --- # Audit Dependabot PRs Audit open dependabot PRs and propose a safe merge order. You are the **team lead**. You orchestrate. You do NOT read source code or run grep yourself during investigation — every codebase walk goes through a sub-agent inside a per-PR investigator. You handle GitHub queries, worktree setup, synthesis, and the merge-order proposal. The skill is **audit-only**. It never merges, pushes, comments on PRs, or removes worktrees. It ends by presenting findings + a proposed sequence and asking the user what to do next. ## Phase 0 — Discovery Args: an optional list of PR numbers (`/audit-deps 77 78 79`). If omitted, audit every open dependabot PR. Run once: ```bash gh pr list --state open --json number,title,headRefName,author,createdAt,mergeable,statusCheckRollup \ --jq '.[] | select(.author.login=="app/dependabot" or (.headRefName | startswith("dependabot/")))' ``` If args were passed, narrow to those PR numbers. From each PR object extract: - PR number, title, head ref - `mergeable` state (`MERGEABLE` / `CONFLICTING` / `UNKNOWN`) - `statusCheckRollup` — count and roll up to "all green" / "N failing" - Age in days (today − `createdAt`) If the result is empty, exit early with a one-line message — no work to do. If any PR has `CONFLICTING` AND age > 7 days, note it as "stale-conflict — rebase candidate" but do NOT trigger a rebase. Rebase decisions belong to Phase 4 (user authorization). State briefly to the user what you found before moving on: > Found N open dependabot PRs: #77 paging, #78 AGP 9.2.1, #79 kotlinx-datetime. Setting up worktrees. ## Phase 1 — Worktree setup Project worktree convention: `.claude/worktrees/deps/pr-` on a local branch named `pr-`. For each PR: ```bash # fetch dependabot branch as local pr- git fetch origin :pr- # create worktree (or refresh if it exists from a prior audit run) if [ -d ".claude/worktrees/deps/pr-" ]; then git -C .claude/worktrees/deps/pr- fetch origin git -C .claude/worktrees/deps/pr- reset --hard pr- else git worktree add .claude/worktrees/deps/pr- pr- fi ``` Never auto-remove worktrees from prior runs — they may be useful for the user post-audit. Worktree cleanup happens only after Phase 4 if the user approves. ## Phase 2 — Parallel investigation Spawn **one investigator per PR** in a **single message** (multiple `Agent` tool calls together so they run concurrently). Each investigator is a one-shot `Agent` call (no `team_name` — Agent Teams are unnecessary here). The investigator's job has two parts: 1. **Upstream research** — the investigator does this itself via `WebFetch` / `WebSearch`. Read release notes, changelog, and (if available) the GitHub compare view between the two versions. 2. **Codebase impact** — the investigator MUST delegate this to a nested sub-agent via its own `Agent` call. The sub-agent reads the project root (not the worktree — current `develop` is the real merge target). The investigator synthesizes upstream + codebase findings into one report. ### Investigator prompt template Pass the investigator everything it needs so it doesn't re-discover: - PR number, worktree path, project root path - Exact files changed in the PR (extract from `gh pr diff --name-only` before spawning) - CI status rollup from Phase 0 (don't make the investigator re-fetch) - Targeted WebFetch URLs — release notes, changelog, GitHub compare view - Word cap on the report (250–400 depending on bump complexity) - Required report fields: - **Breaking changes**: bullet list, or `none — patch` - **Codebase impact**: file count + specific call sites with `path:line`, authored by the sub-agent - **Sequencing constraints**: e.g., "requires Gradle 9.5+ — depends on PR #76", or `none` - **Risk**: `Low` / `Medium` / `High` + one-line justification - **Recommendation**: `merge as-is` / `merge with caveats (...)` / `hold (...)` Include these flags in the prompt when applicable: - **Kotlin/KMP bump** (Kotlin, AGP, Compose, KSP, Ktor, Koin, serialization, SKIE, mokkery, anything hooking the K2 compiler): the investigator MUST first **enumerate every plugin in `gradle/libs.versions.toml` that touches the Kotlin compiler or Kotlin/Native**, then check each for compatibility. Do NOT pre-list dependencies for the investigator to verify — pre-listing causes blind spots. SKIE specifically has been missed twice this way (2026-04-25, 2026-05-06); check [touchlab/SKIE releases](https://github.com/touchlab/SKIE/releases) and open issues directly, not just variant attributes. - **Pre-1.0 minor bump** (`0.x.y → 0.z.0`): apply extra scrutiny — pre-1.0 minor bumps can break source/binary API even on green CI. Explicitly check for renamed/relocated symbols that still compile via deprecated aliases. - **AGP bump**: if the release notes touch R8, proguard, manifest merger, or lint, the recommendation must include "release-build smoke test (login → conversations → chat)" as a caveat. ### Sub-agent prompt template (codebase walk) The investigator constructs this and passes it to a nested `Agent` call: - Project root path (the live `develop` checkout, not the worktree) - A grep list specific to the library — symbols, imports, common type names, build-script keys (e.g., for paging: `import androidx.paging`, `PagingSource`, `Pager(`, `LazyPagingItems`, `RemoteMediator`, `paging-compose`) - The new API surface and any deprecations from the upstream changelog the investigator just fetched (so the sub-agent knows which call sites are at risk) - Report format: - File count: how many files touch this library? - Call sites: list with `file:line` - Deprecation/removal exposure: which call sites use APIs flagged by the upstream changelog as changed/deprecated/removed, with explicit `file:line` - KMP source-set coverage: does usage live in commonMain, androidMain, iosMain, or tests? - Word cap: 200 words The investigator returns a combined report. Word cap is the investigator's, not the sum. ## Phase 3 — Synthesis and merge-order proposal After all investigators return, produce two artifacts in the response. ### 1. Comparison table One row per PR. Columns: ``` | # | Bump | CI | Breaking changes | Codebase impact | Sequencing | Risk | Recommendation | ``` Include every PR Phase 0 enumerated. No silent drops — if an investigator failed, surface the failure rather than omitting the row. ### 2. Proposed merge order A numbered list, each entry naming the PR and a one-line rationale. Ordering rules (priority order): 1. **Independent green low-risk first** — CI-green + Low risk + no sequencing constraints. These are warm-ups; merging them first reduces rebase churn for everything that follows. 2. **Respect sequencing constraints** — if PR B requires PR A (e.g., Gradle ≥ 9.5 → AGP), A goes first. 3. **Config-patch-needed last among non-blocked** — PRs that need a small config tweak alongside the bump (detekt rule overrides, proguard addition, etc.) sit at the end of the non-blocked set, so green PRs don't get gated behind config work. 4. **Hold last with a `BLOCKED` tag** — PRs flagged "hold" (CI blocker, breaking change requiring code, awaiting upstream fix) sit at the end with the unblocking condition stated explicitly. State the *why* on every line. The user reads the rationale to override the order if needed. ## Phase 4 — User authorization Ask the user via `AskUserQuestion` what to do. Typical options to offer: - Merge all green / merge a subset - Push config patch for PR #X (if applicable) - Trigger `@dependabot rebase` on stale-conflict PRs - Hold all (leave PRs untouched, exit) - Cancel The skill exits after presenting. **Execution happens outside the skill** — the user authorizes each action explicitly so per-action control is preserved. This is intentional; don't try to bundle "merge + push patch + comment" behind a single approval inside the skill. ## Anti-patterns to avoid These come from prior runs (sessions `3ae98b8c` 2026-05-05 and the 2026-05-11 follow-up): - **Don't pre-list dependencies for the investigator to check.** Make them enumerate from `libs.versions.toml`. Pre-listing causes blind spots (SKIE missed twice). - **Don't trust "CI green" to mean "safe"** for pre-1.0 minor bumps. Deprecated aliases still compile; flag them anyway. - **Don't auto-trigger rebases or auto-merge.** Both are user-authorized actions even when "the fix is obvious." The cost of pausing is low; the cost of a wrong auto-merge is high. - **Don't drop a PR from the table** if the investigator failed. Surface the failure as a row marked `[INVESTIGATOR FAILED]` so the user sees it. - **Don't read source files yourself as the team lead.** Codebase walks always go through the per-PR investigator's sub-agent.