Dependabot Fix

Dependabot Fix

Systematically fix a failing Dependabot PR. The user provides a PR number (e.g., /dependabot-fix 142).

This skill spans five phases (A–E). Do not start editing code until Phase D is complete. Do not dive into logs until Phase B is complete.

Set up scratch space once at the start:

mkdir -p ./tmp && touch ./tmp/null
PR_NUM=<from user prompt>
REPO=axsaucedo/kaos

Phase A — Context

Step 1 · PR context

Fetch metadata and produce a one-paragraph written summary of the PR (ecosystem, directory, grouping, size, whether it is a security update, which files it touches). Do not open source files yet.

gh pr view $PR_NUM --repo $REPO --json title,body,headRefName,labels,files,mergeable,createdAt
gh pr diff $PR_NUM --repo $REPO | head -200

Identify:

• Ecosystem: github_actions | gomod | uv / pip | npm | docker
• Directory scope (/, operator/, pydantic-ai-server/, kaos-cli/, kaos-ui/, operator/tests/, mcp-servers/*, docs/)
• Grouping: single-dep vs grouped (all, all-security)
• Size: list number of files and approximate LOC changed

Step 2 · High-level error survey

List failing checks and capture the first and last error line from each failing job log. Do not investigate their meaning yet — just enumerate symptoms.

gh pr checks $PR_NUM --repo $REPO

# For each failing check, grab job ID from the URL and pull logs
gh run view --job <JOB_ID> --repo $REPO --log 2>./tmp/null \
  | grep -iE "error|exit code|##\[error\]|FAILED|assert|timed ?out" \
  | head -20 > ./tmp/pr-${PR_NUM}-symptoms.txt

Output should be a bullet list such as:

• go-tests/unit-tests: controller-tools@v0.20.1 requires go >= 1.25.0
• kaos-ui-tests/unit: TypeError: Cannot read properties of undefined (reading 'forEach') in dashboard.test.ts
• python-tests/pydantic-ai-server: AssertionError: expected 2 tool calls, got 3

Phase B — Context ingestion via subagents

Spawn three parallel explore subagents to load repo knowledge scoped to the touched ecosystems. Do not read any of this yourself beforehand — delegate.

Step 3 · Instructions subagent

Ask it to read .github/instructions/*.instructions.md files relevant to the PR's touched paths and summarize conventions, test commands, and gotchas.

Mapping guide (pass relevant ones to the subagent):

• operator/** or gomod bumps → operator.instructions.md, e2e.instructions.md
• pydantic-ai-server/**, kaos-cli/**, uv / pip bumps → python.instructions.md
• kaos-ui/** or npm bumps in kaos-ui/ → kaos-ui.instructions.md, kaos-ui-components.instructions.md, kaos-ui-testing.instructions.md, kaos-ui-kubernetes-types.instructions.md
• docs/** or npm bumps in docs/ → docs.instructions.md
• .github/workflows/** (github_actions PRs) → release/CI-relevant instructions from above, plus .github/copilot-instructions.md

Step 4 · Docs subagent

Ask it to read matching docs/ pages for the changed modules: module overview, testing notes, architecture diagrams. Return a briefing no longer than ~40 lines covering what the module does, its public surface, and how it is tested.

Step 5 · Codebase subagent

Ask it to produce a targeted map:

• Primary source directories and entry points for the touched area
• Build and test commands (e.g. make test-unit, npm run test:unit, python -m pytest …)
• Integration/E2E entry points (operator/tests/e2e, kaos-ui/tests/**)
• Any Makefile targets that generate code (make generate manifests, make helm)
• Docker images built from this code (for local reproduction)

The three subagent briefings together form the working context for Phase C.

Phase C — Deep root-cause diagnosis

Step 6 · Diagnose

Now — and only now — dive into the failing-job logs with full context from Phase B. For each failing check, trace the first meaningful error back to:

1. A direct regression from the bumped dep (removed symbol, signature change, behaviour change, stricter validation)
2. A transitive toolchain issue (e.g. @latest pulling a newer Go/Node/Python; post-install script requiring newer runtime)
3. Pre-existing test fragility exposed by a harmless dep bump
4. Infra flake (post-job cancellation after tests passed, timeouts, registry rate-limits)

For a grouped PR, diagnose each failing check separately — failures may have independent causes. Record findings in ./tmp/pr-${PR_NUM}-diagnosis.md.

Phase D — Fix design

Step 6.5 · Scope triage — is this a fix, or a Dependabot config problem?

Before planning a fix, check whether the PR is in-scope for fixing at all. A grouped Dependabot PR that bundles framework-migration majors cannot be fixed in a single pass; the right move is to reconfigure .github/dependabot.yml so the majors come through individually.

Scope-reject triggers (any one is sufficient):

• A single group PR contains ≥ 2 major bumps on framework-tier packages
• A major bump on: react, react-dom, react-router-dom, vite, vitest, @tanstack/react-query, tailwindcss, typescript, eslint, zod, zustand (npm); controller-runtime, k8s.io/*, pydantic, pydantic-ai, litellm (other ecosystems) when bundled with unrelated updates
• The PR touches > ~40 packages and the majority are routine but a minority are migrations

When triggered, do not attempt a fix and do not close the PR yourself — leave it open for the host to close. Instead:

1. Update .github/dependabot.yml to split the offending group (typically add update-types: ["minor", "patch"] to the all group so majors get individual PRs).
2. Open that config change as a separate small PR (leave it for the host to review/merge).
3. Verbalise the scope-reject decision as a comment on the original Dependabot PR(s): explain why it cannot be fixed in one pass, link the config PR, and recommend the host close it once smaller PRs replace it next cycle. Leave the PR open — do not pause for a decision, do not close it.
4. Skip Phase E's "commit on Dependabot branch" flow — there is no fix. The REPORT.md content can be folded into that comment.

Security-update groups (all-security) are usually left bundled because security majors are rare and time-sensitive — only split them if a concrete blocker (e.g. a framework major) forces it.

Step 7 · Comprehensive plan

Write a plan covering the following; scale depth to risk:

Risk ≥ medium if any of:

• bump touches public API of an exported library (gomod, kaos-cli, pydantic-ai-server)
• changes a Kubernetes CRD generated surface
• changes an HTTP/JSON-RPC wire format
• changes a runtime image that ships in a release

Step 8 · Manual testing strategy (tiered)

Tier the effort by Step 7's risk rating:

• Low (isolated) — apply fix, run the narrowest relevant suite (e.g. one pytest file, one vitest spec, go test ./pkg/...). No reproduction step needed.
• Medium (cross-module or cross-ecosystem) — first reproduce the failure on main locally to prove the regression is real (not a harness artefact). Then apply the fix, retest, and confirm the reproduction no longer fires.
• High (runtime / wire) — reproduce against a locally-built Docker image for the affected component (see ecosystem appendix). If it touches operator/agent behaviour, bring up a KIND cluster per .github/instructions/e2e.instructions.md and run 1–3 E2E tests locally before pushing.

Keep all scratch output under ./tmp/. Use ./tmp/null as the sink when suppressing output:

python -m pytest tests/test_x.py -v 2>./tmp/null

Phase E — Finalise

Step 9 · Ship directly on the Dependabot PR

Keep it simple: commit fixes on the existing Dependabot PR branch. No replacement PR, no cherry-picking.

gh pr checkout $PR_NUM --repo $REPO

# ...make edits...
git add -A
git commit -m "ci(<scope>): <one-line summary>

Root cause: <one sentence>
Fix: <one sentence>
Testing: <how verified>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"

git push

Monitor CI; rerun known flakes once before investigating:

gh pr checks $PR_NUM --repo $REPO
gh run rerun <run-id> --failed --repo $REPO  # only for known flakes

Merge when green — but for kaos-ui framework major bumps, leave the PR open for human review instead of merging (see Step 9.5):

gh pr merge $PR_NUM --repo $REPO --merge

Caveats:

• Do not use @dependabot rebase after pushing fix commits — it will discard them. Let the PR merge as-is.
• If Step 9.5 says leave-open (kaos-ui framework major), do not merge. Post the report and leave the PR open; the host merges after their own visual review.

Step 9.5 · kaos-ui review gate (framework majors only)

The visual/E2E suite for kaos-ui is stringent, so minor and patch bumps — including framework packages — can be merged directly once CI is green. No human gate is needed for them.

For a kaos-ui major bump on a framework package (react, react-dom, react-router-dom, vite, vitest, @tanstack/react-query, tailwindcss, typescript, eslint, zod, zustand), CI alone is insufficient evidence — major-version visual regressions can slip past Playwright assertions. Do not merge. Instead:

1. Push the fix commits so CI is green.
2. Post REPORT.md as a PR comment (Step 10), explicitly noting it is a framework major held for human visual review.
3. Leave the PR open. The host reviews and merges manually.

Do not use the ask_user tool or any in-chat prompt as a merge gate — it does not reliably block execution. The gate is simply "leave the major PR open"; the human review happens on the PR itself.