garfiec / audit-deps

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:

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-<N> on a local branch named pr-<N>.

For each PR:

# fetch dependabot branch as local pr-<N>
git fetch origin <head-ref>:pr-<N>

# create worktree (or refresh if it exists from a prior audit run)
if [ -d ".claude/worktrees/deps/pr-<N>" ]; then
  git -C .claude/worktrees/deps/pr-<N> fetch origin
  git -C .claude/worktrees/deps/pr-<N> reset --hard pr-<N>
else
  git worktree add .claude/worktrees/deps/pr-<N> pr-<N>
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 <N> --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 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.