Advanced Gradle Dependency Engineering

Diagnoses and fixes advanced Gradle dependency resolution problems as diagnose-to-fix loops across the operate/author split. This skill owns the cross-cutting lane between everyday dependency inspection (using-gradle) and basic dependency authoring (authoring-gradle-builds).

Positive Triggers (when to activate)

• Variant selection failures or attribute mismatches, diagnosed via outgoingVariants and dependencyInsight --all-variants
• Dependency verification metadata, PGP keys, and CI verification workflows
• Component metadata rules, selection rules, dependency substitution, and composite build diagnosis
• Capability conflicts, feature variants, lock modes, advanced version catalogs beyond everyday catalog entries, repository governance, and caching/freshness tuning

Negative Triggers (when NOT to activate)

• Everyday dependency inspection, conflicts, or updates -> using-gradle
• Dependency declarations, basic version catalogs, or basic locking -> authoring-gradle-builds
• Running builds or generic failure diagnosis -> using-gradle
• Non-dependency structural authoring -> authoring-gradle-builds

More info: Search the User Guide with gradle_docs(query="tag:userguide <term>"). Read gradle/wrapper/gradle-wrapper.properties before any version-sensitive advice; this skill's wrapper-first scoping is mandatory because resolution behavior is version-sensitive.

Constitution

• ALWAYS use the Gradle MCP gradle tool (or the dedicated dependency inspection tools) instead of ./gradlew via shell for all resolution work.
• ALWAYS read the wrapper version (gradle/wrapper/gradle-wrapper.properties) before applying version-sensitive advice; resolution reports, variant model behavior, and governance modes change across Gradle versions.
• ALWAYS diagnose before fixing: run the matching authoritative report first (dependencyInsight, outgoingVariants, graph inspection), then apply the minimal authoring fix, then re-run the diagnostic to confirm resolution.
• ALWAYS use query_build(kind="TESTS") for tests and query_build for diagnostics; avoid raw console parsing.
• NEVER prescribe a resolution fix without a diagnostic step; variant mismatches, capability conflicts, and substitution behavior must be evidenced before authoring a rule.
• NEVER fabricate tool names; cite authoritative documentation only through gradle_docs hints (path=... or query="tag:...").
• Handoff: everyday dependency inspection belongs to using-gradle; basic dependency declaration, version-catalog basics, and basic locking belong to authoring-gradle-builds; see Cross-Skill Handoffs.

Decision Routing

Advanced dependency task	Reference
Diagnose variant selection failures, attribute mismatches, or no-matching-variant errors	Variant Resolution Diagnostics
Enable or repair dependency verification (verification-metadata.xml, PGP keys, checksums, CI)	Dependency Verification
Author or troubleshoot component metadata rules and dependency selection rules	Component Metadata Rules
Diagnose dependency substitution or composite-build resolution (composite authoring lives in authoring-gradle-builds)	Substitution and Composites
Resolve feature-variant selection, configuration-role, or capability-conflict problems	Feature Variants and Capabilities
Apply lock modes or deep locking behavior beyond the basics	Dependency Locking Deep Dive
Author advanced version catalog topics (bundles, plugins, multiple catalogs, composition)	Advanced Version Catalogs
Govern repository declaration modes, content filtering, or exclusiveContent	Repository Governance
Reason about dependency cache freshness, resolution consistency, or resolution avoidance/performance	Resolution Mechanics
Research Gradle internals, resolution mechanics, or dependency source	Research

Provenance and Consumer Routing

Agent question	Route
Why this version?	Use dependencyInsight, then interpret the selected version (selected.version) with reason, isDirect, and fromConfiguration from inspect_dependencies. Treat latestVersion only as an optional advisory "newer available" signal; never use it to explain why the selected version won.
Who depends on X?	Make one inspect_dependencies { filter=X, includeConsumers:true } call, then read the target's consumers list. onlyDirect=false is implied, so the full resolved graph is inverted without passing onlyDirect=false yourself.
What is the blast radius?	Filter the target dependency and traverse successive direct consumers edges client-side. There is no server-side transitive-closure API.

Reference Discovery

Read the linked reference as part of the workflow: use Variant Resolution Diagnostics when a variant selection fails or attributes do not match; use Dependency Verification when explicitly asked to enable, repair, or CI-integrate verification-metadata.xml; use Component Metadata Rules when a resolution outcome is wrong and a component metadata or selection rule is the correct lever; use Substitution and Composites when a replacement, module dependency substitution, or composite build diagnosis is needed; use Feature Variants and Capabilities for feature-variant selection, configuration-role, and capability-conflict resolution; use Dependency Locking Deep Dive for lock modes and deep locking behavior; use Advanced Version Catalogs for catalog topics beyond everyday entries; use Repository Governance for dependencyResolutionManagement modes, content filtering, and exclusiveContent; and use Resolution Mechanics when reasoning about caching/freshness, resolution consistency, or resolution avoidance and performance.

Cross-Skill Handoffs

• Everyday Dependency Inspection (graph audits, dependencyInsight winner analysis, force/exclude/platform/constraint menu, cache TTL vs --refresh-dependencies, update discovery, trivial dependency edits) $\rightarrow$ using-gradle.
• Basic Dependency Authoring (dependency declarations, version-catalog basics, repositories and content filters, constraints/BOMs, basic locking, custom-attribute/feature-variant basics) $\rightarrow$ authoring-gradle-builds.
• Composite Build Authoring (includeBuild declarations, plugin-management inclusion, buildSrc vs composite trade-offs, cross-build task wiring) $\rightarrow$ authoring-gradle-builds. This skill keeps composite-build diagnosis and dependency-substitution authoring.
• Receives advanced dependency engineering routed out of using-gradle and authoring-gradle-builds.

Workflows

Diagnose a Variant Selection Failure

1. Load Variant Resolution Diagnostics.
2. Read the wrapper version and record the failing configuration and requested attributes.
3. Diagnose with dependencyInsight --all-variants and the outgoingVariants report before authoring any rule.
4. Apply the minimal fix: an attribute compatibility or disambiguation rule on the correct side of the resolution.
5. Re-run the diagnostic to confirm the variant now matches.
6. When resolution behaves differently between local and CI, a published Build Scan / Develocity Analytics can expose resolution and repository differences across builds for comparison. Develocity publishes an llms.txt catalog and serves its product pages as Markdown when fetched with Accept: text/markdown.

Enable or Repair Dependency Verification

1. Load Dependency Verification.
2. Confirm the request is an explicit supply-chain hardening request; report the UX costs first per the conditional-only doctrine.
3. Author or repair verification-metadata.xml (PGP keys, checksums, CI workflow) per the reference.
4. Re-run resolution to confirm verification is satisfied without disabling it.

Correct a Wrong Resolution Outcome

1. Confirm the wrapper version and the resolved graph via inspect_dependencies / dependencyInsight.
2. Identify whether the cause is a component metadata rule, a selection rule, substitution, or a capability conflict by loading the matching reference.
3. Apply the smallest rule, then re-run the diagnostic to confirm the winner changed as intended.