playbooks

home / skills / shotaiuchi / dotclaude / debug-dependency

debug-dependency skill

/dotclaude/skills/debug-dependency

This skill investigates dependency and version issues causing build failures or runtime errors, identifying conflicts, breaking changes, and transitive

npx playbooks add skill shotaiuchi/dotclaude --skill debug-dependency

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: debug-dependency
description: >-
  Dependency and version investigation. Apply when debugging version conflicts,
  breaking changes in libraries, transitive dependency issues, and
  incompatibility errors.
user-invocable: false
---

# Dependency Auditor Investigation

Investigate dependency and version issues that cause build failures or runtime errors.

## Investigation Checklist

### Version Compatibility
- Check declared version constraints against installed versions
- Identify version range specifications that resolve to incompatible releases
- Verify peer dependency requirements are satisfied
- Look for version pinning that prevents necessary updates
- Check for diamond dependency conflicts with incompatible versions

### Breaking Changes
- Review changelogs for breaking changes between current and expected versions
- Identify removed or renamed APIs causing compile or runtime errors
- Check for behavior changes in existing APIs that alter semantics
- Verify default value changes that affect implicit configurations
- Look for deprecation warnings that preceded the breaking change

### Transitive Dependencies
- Map the full dependency tree to find conflict sources
- Identify duplicate packages at different versions in the tree
- Check for transitive dependencies that override direct declarations
- Verify resolution strategies do not silently pick wrong versions
- Look for phantom dependencies used but not declared explicitly

### Runtime vs Build Dependencies
- Verify build-time dependencies are not leaking into runtime
- Check for missing runtime dependencies excluded during packaging
- Identify development dependencies incorrectly marked as production
- Verify native binary dependencies match the target platform
- Look for optional dependencies that fail silently at runtime

## Output Format

Report findings with confidence ratings:

| Confidence | Description |
|------------|-------------|
| High | Root cause clearly identified with supporting evidence |
| Medium | Probable cause identified but needs verification |
| Low | Hypothesis formed but insufficient evidence |
| Inconclusive | Unable to determine from available information |

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

FAQ

What evidence supports a High confidence finding?

High confidence requires direct evidence such as resolved lockfile entries, stack traces referencing a specific package version, or changelog entries documenting the breaking change.

How do you handle cases with insufficient metadata?

When metadata is missing, the skill produces Medium or Low confidence hypotheses and recommends collecting lockfiles, reproducible builds, and runtime logs for verification.