debug-dependency_skill

Overview

This skill inspects dependency and version problems that cause build failures or runtime errors. It helps identify version conflicts, breaking changes, transitive dependency issues, and runtime vs build dependency mismatches. The output is a concise investigative report with confidence ratings and actionable next steps.

How this skill works

The skill maps the full dependency tree, compares declared constraints to resolved versions, and flags diamond or duplicate package situations. It inspects changelogs and API changes for likely breaking changes, checks peer and transitive dependency satisfaction, and verifies whether build-time and runtime dependencies are correctly classified. Findings are reported with a High/Medium/Low/Inconclusive confidence level and recommended remediation steps.

When to use it

• Build failures referencing missing or incompatible packages
• Runtime errors after upgrading a library or framework
• Suspected transitive dependency pulling an unexpected version
• Peer dependency warnings or unresolved peer requirements
• Packaging issues where dev dependencies leak into production

Best practices

• Pin or constrain versions deliberately and document why range choices were made
• Check changelogs and migration guides before upgrading major versions
• Map and lock full dependency trees (lockfiles) to prevent surprises
• Separate build and runtime dependencies clearly in packaging/config
• Use automated dependency audits and CI checks for version drift

Example use cases

• A CI build breaks after a minor package update—investigate which transitive change introduced the break
• An app crashes in production due to a missing native binary dependency not included in the build artifact
• Multiple versions of the same library cause classloader or symbol conflicts—identify the diamond conflict root
• Peer dependency warnings appear during install—verify consumer/peer version compatibility and adjust constraints
• Upgrading a framework introduced a renamed API—trace the change through changelogs and dependency graph