version-doctor

name	version-doctor
description	Diagnose and fix library version mismatches, dependency conflicts, and build file inheritance issues. Use when the user says "fix versions", "version mismatch", "dependency conflict", "why won't this build", or "update dependencies", and proactively when a build fails on version constraints — the fix is almost always a version bump, not restructuring the build. Use this before rewriting a build config or bypassing workspace inheritance.
model	sonnet
effort	medium
allowed-tools	Read, Grep, Glob, Bash, Agent

version-doctor

Fix version mismatches by updating versions, not restructuring builds.

The #1 failure mode when AI encounters a build error: it treats a version mismatch as "wrong approach" and restructures the entire build config. The correct response is almost always: change one version number.

Core Principle

Version mismatch = fix the version. Not restructure the build.

Build configs have inheritance chains (workspace → member). When a version conflict appears, the inheritance is correct — the version is wrong. Respect the architecture.

Protocol

Step 1: Map the config chain

Read the full inheritance chain before touching anything:

workspace root config → intermediate configs → the file with the error

For each build system:

• Rust: Cargo.toml (workspace root) → member Cargo.toml files
• Python: pyproject.toml (workspace root with uv) → member packages
• Node: root package.json → workspace package.json files
• Go: go.work → member go.mod files
• JVM: settings.gradle + root build.gradle → subproject build.gradle

Read the relevant reference file from references/ for the specific build system.

Step 2: Diagnose

Classify the error:

Error Type	Symptom	Fix
Version mismatch	"expected X, found Y"	Update version constraint
Missing dependency	"not found" / "no matching"	Add to correct config level
Inheritance broken	Child duplicates parent config	Remove child override, use inheritance
Yanked/removed version	"version X not available"	Find latest compatible version
Conflicting constraints	"impossible to satisfy"	Unify constraints at workspace level

Step 3: Research (when needed)

If the correct version isn't obvious:

1. Context7 first — spawn a research agent to fetch current docs for the library:

   Use Context7 to check: what is the latest version of <library>?
   What changed between version X and Y?
   

2. Changelog/migration guide — for major version bumps, check if there are breaking changes that require code changes alongside the version bump

3. Compatibility matrix — some libraries pin to specific ranges of their dependencies. Check the library's own build config for constraints.

Step 4: Fix

Apply the minimum change:

1. Update the version number in the correct config file (usually workspace root)
2. Run the lock file update (cargo update, uv lock, npm install, go mod tidy)
3. If code changes needed (rare, only for major version bumps): make them, but flag to the user that this is a breaking change fix, not just a version bump

Step 5: Verify

Run the build to confirm the fix works (rtk filters output automatically):

Build System	Verify Command
Rust	cargo check
Python (uv)	uv lock && uv run python -c "import <pkg>"
Node	npm install && npm run build
Go	go build ./...
JVM	gradle build

What NOT to do

These are the panic responses that waste the user's time:

• Don't bypass workspace inheritance — if a member config inherits from workspace, don't copy everything into the member to "fix" a version issue
• Don't create standalone configs — replacing an inherited config with a standalone one breaks the project's build architecture
• Don't downgrade to avoid conflicts — find the version that satisfies all constraints, don't retreat to an old version that sidesteps the problem
• Don't restructure the dependency tree — if the workspace declares dep X at version 1.0 and you need 2.0, update the workspace, don't fork the dep
• Don't roll custom build scripts — if the build tool has a config option, use it

Output Format

Present findings as:

## Diagnosis
<what's wrong — one sentence>

## Root Cause
<which config file, which version constraint, why it conflicts>

## Fix
<exact change — file path, old value → new value>

## Verification
<command to run to confirm>