Java Build and Dependencies
Purpose and boundary
Find the build input that explains the failure. For a repair request, make the smallest
compatible change and verify the affected path; for diagnosis or review only, report
the evidence, proposed correction and discriminating check without editing the build.
A declaration, an effective model, a resolved configuration, a packaged artifact and
a running process are different evidence.
Basic repository discovery is covered by feature-context-analysis. This skill
continues from that evidence into build diagnosis and repair. For intentional JDK
migration consider jdk-upgrade-impact; for loader identity, initialization and JPMS
access consider jvm-class-loading. Publication and consumer compatibility decisions
belong to component-and-release-boundaries; comprehensive supply chain and CI gate
design belongs to quality-gates. These are optional neighbors, not prerequisites
for a scoped build fix. For a handoff, pass the failing invocation, selected graph,
actual JVMs, relevant artifact/class and remaining question; request the neighbor's
specific compatibility or loader assessment. If unavailable, retain those findings
and identify the unresolved check rather than broadening the repair speculatively.
Establish the execution context
Inspect the wrapper/version, target module, active Maven profiles or Gradle
configuration, CI invocation, build plugins, repositories and relevant existing
reports. Preserve the project's Java, framework and build-tool baselines. This
skill does not prescribe a Java release or authorize upgrades to fit an example.
Reference recipes use Maven 3 and Gradle 8.14.3 documentation; match syntax and
behavior to the target wrapper and plugin versions before applying them.
Separate documented compatibility requirements from repeated conventions and incidental
configuration. Reuse existing evidence before asking. If an unknown changes the repair
(for example, whether the deployment container supplies a provided API), ask that
focused question while continuing independent diagnosis. State consequential assumptions;
do not infer a production Java baseline from the developer's installed JDK. Routine,
reversible choices within an authorized repair do not require another approval.
Before invoking an unfamiliar wrapper or build, inspect its provenance, scripts,
distribution URL and applicable checksum verification. Build configuration and
plugins can execute code even for report tasks. Use the authorized environment;
keep synthetic reproductions and their repositories/caches isolated. Do not run
publication, deployment or global installation as a diagnostic step.
Record separately the JVM launching Maven/Gradle, any Gradle daemon JVM, compiler
toolchain, compiler release, test JVM and deployment JVM. java -version in one
shell establishes only that executable. A compiler release limits language/JDK API
usage and class-file target; it neither chooses the production JVM nor retargets
third-party JARs. Read toolchains and reproducibility
when these identities differ, a wrapper changes, or the task makes a repeatability claim.
Also read its generated-code section when a generated type or processor effect disappears;
the compiler's processing policy is separate from the application's release target.
Workflow
- Locate the failing phase and owner. Capture the exact invocation and first
relevant failure: model/configuration, artifact resolution, plugin execution,
compile, test, packaging or application startup. Identify the module and
configuration that needs the missing class or version. A plugin failure is not
automatically an application dependency failure.
- Inspect the selected graph. For Maven read
Maven diagnosis; for Gradle read
Gradle diagnosis. Record the coordinate, requested and
selected versions, introducing path, scope/configuration and selection rule.
A BOM, dependency-management entry, version catalog or constraint alone does
not establish that an artifact is present.
Inspect unresolved nodes and diagnostics even when a report exits successfully;
a selected metadata graph does not prove that its artifact files can be obtained.
- Form a discriminating explanation. Connect the observed graph or toolchain
to the error. Compare compile, test and runtime evidence only where the failure
requires it. For packaged applications inspect the produced distribution/image
and launch classpath as well; the build graph does not prove deployment contents.
If reports cannot run, state the declared information, unresolved selection and
smallest missing check. Do not invent a resolved version.
- Choose the narrowest correct repair. When fixes are requested, correct an absent direct dependency,
wrong scope/configuration, mistaken management entry, plugin dependency or
toolchain selection according to the evidence. Respect an intentional platform
version family. A targeted management override or constraint needs a compatibility
reason and a check; a global force, transitivity disable or broad exclusion is
not a default conflict fix. Do not upgrade unrelated dependencies.
- Verify the causal path. For an implemented change, compare the relevant graph before/after, rerun the
failing task and an affected test or launch check. Check that requested tests
actually ran; success with zero tests or an up-to-date task is not fresh execution.
If a changed library is published, inspect generated consumer metadata and use
a separate consumer when that contract is in scope. Do not claim a runtime fix
from compilation alone.
Decision rules
- Managed but absent: first establish an actual dependency path. Add a dependency
only to the module/configuration that needs it; changing the BOM version cannot
supply an artifact that is never included.
- Conflicting versions: use the build tool's selection evidence. Maven's nearest
definition and Gradle's ordinary highest eligible version selection are different
rules, both affected by explicit management/constraints. Neither proves binary or
behavioral compatibility.
- Exclusion proposed: identify the introducing edge, the feature losing that
artifact and any alternate path that still includes it. Exercise that feature or
replacement. An exclusion removes an edge; it does not repair incompatible APIs.
- Compile succeeds, runtime fails: examine runtime inclusion, packaging and the
deployed JVM. Test dependencies, provided/compile-only APIs and a newer dependency's
bytecode are concrete hypotheses. If artifacts and versions are correct but loader
behavior remains in question, retain the evidence for the class-loading handoff.
- Generated code is missing: identify the generator/processor and failing source set.
Inspect its execution path, compiler options and generated-output registration before
adding an application dependency. Annotation APIs, processor implementations, generated
output and runtime support have different classpath roles; one does not imply the others.
- Local succeeds, CI fails: compare wrapper, profiles/properties, toolchains,
repository/mirror access, selected versions and bytes before clearing anything.
Avoid deleting shared caches or using refresh/update flags until there is a cache
hypothesis; preserve the failing evidence and refresh narrowly when justified.
- Locked therefore reproducible: identify configurations covered by lock state,
mutable artifacts, verification policy and actual outputs compared. A same-version
SNAPSHOT can have different bytes. Keep version repeatability, artifact integrity
and byte-for-byte build reproducibility as separate claims.
Minimum result
For a small fix, a short explanation and diff are enough. Include the failing target,
evidence for the selected dependency/toolchain, causal explanation or remaining
hypothesis, scoped change, and checks actually executed. Name unavailable evidence
and the next check explicitly. A diagnosis or review finishes with supported findings,
their consequences, a scoped proposed correction and verification still needed; it
does not require a patch or claim an unexecuted repair succeeded.
For a repair, stop when the original failure is addressed and the
affected behavior is verified, or when a material external gap has a concrete
resolving action. Do not turn the repair into a build-system migration.
1---2name: java-build-and-dependencies3description: >-4 Diagnose and repair Maven or Gradle builds when a managed dependency is missing,5 a transitive version wins unexpectedly, compilation and runtime classpaths differ,6 or the launcher JDK, toolchain and release target disagree. Use for dependency7 conflicts, missing runtime artifacts or generated code, plugin classpath failures8 and unreliable dependency resolution. Covers focused build repairs and reproducibility checks;9 intentional JDK upgrades, classloader internals and published-library governance10 belong to neighboring skills.11metadata:12 source: https://skillmd.com/skills/robsonkades/java-build-and-dependencies13---1415# Java Build and Dependencies1617## Purpose and boundary1819Find the build input that explains the failure. For a repair request, make the smallest20compatible change and verify the affected path; for diagnosis or review only, report21the evidence, proposed correction and discriminating check without editing the build.22A declaration, an effective model, a resolved configuration, a packaged artifact and23a running process are different evidence.2425Basic repository discovery is covered by `feature-context-analysis`. This skill26continues from that evidence into build diagnosis and repair. For intentional JDK27migration consider `jdk-upgrade-impact`; for loader identity, initialization and JPMS28access consider `jvm-class-loading`. Publication and consumer compatibility decisions29belong to `component-and-release-boundaries`; comprehensive supply chain and CI gate30design belongs to `quality-gates`. These are optional neighbors, not prerequisites31for a scoped build fix. For a handoff, pass the failing invocation, selected graph,32actual JVMs, relevant artifact/class and remaining question; request the neighbor's33specific compatibility or loader assessment. If unavailable, retain those findings34and identify the unresolved check rather than broadening the repair speculatively.3536## Establish the execution context3738Inspect the wrapper/version, target module, active Maven profiles or Gradle39configuration, CI invocation, build plugins, repositories and relevant existing40reports. Preserve the project's Java, framework and build-tool baselines. This41skill does not prescribe a Java release or authorize upgrades to fit an example.42Reference recipes use Maven 3 and Gradle 8.14.3 documentation; match syntax and43behavior to the target wrapper and plugin versions before applying them.4445Separate documented compatibility requirements from repeated conventions and incidental46configuration. Reuse existing evidence before asking. If an unknown changes the repair47(for example, whether the deployment container supplies a `provided` API), ask that48focused question while continuing independent diagnosis. State consequential assumptions;49do not infer a production Java baseline from the developer's installed JDK. Routine,50reversible choices within an authorized repair do not require another approval.5152Before invoking an unfamiliar wrapper or build, inspect its provenance, scripts,53distribution URL and applicable checksum verification. Build configuration and54plugins can execute code even for report tasks. Use the authorized environment;55keep synthetic reproductions and their repositories/caches isolated. Do not run56publication, deployment or global installation as a diagnostic step.5758Record separately the JVM launching Maven/Gradle, any Gradle daemon JVM, compiler59toolchain, compiler release, test JVM and deployment JVM. `java -version` in one60shell establishes only that executable. A compiler release limits language/JDK API61usage and class-file target; it neither chooses the production JVM nor retargets62third-party JARs. Read [toolchains and reproducibility](references/toolchains-and-reproducibility.md)63when these identities differ, a wrapper changes, or the task makes a repeatability claim.64Also read its generated-code section when a generated type or processor effect disappears;65the compiler's processing policy is separate from the application's release target.6667## Workflow68691. **Locate the failing phase and owner.** Capture the exact invocation and first70 relevant failure: model/configuration, artifact resolution, plugin execution,71 compile, test, packaging or application startup. Identify the module and72 configuration that needs the missing class or version. A plugin failure is not73 automatically an application dependency failure.742. **Inspect the selected graph.** For Maven read75 [Maven diagnosis](references/maven.md); for Gradle read76 [Gradle diagnosis](references/gradle.md). Record the coordinate, requested and77 selected versions, introducing path, scope/configuration and selection rule.78 A BOM, dependency-management entry, version catalog or constraint alone does79 not establish that an artifact is present.80 Inspect unresolved nodes and diagnostics even when a report exits successfully;81 a selected metadata graph does not prove that its artifact files can be obtained.823. **Form a discriminating explanation.** Connect the observed graph or toolchain83 to the error. Compare compile, test and runtime evidence only where the failure84 requires it. For packaged applications inspect the produced distribution/image85 and launch classpath as well; the build graph does not prove deployment contents.86 If reports cannot run, state the declared information, unresolved selection and87 smallest missing check. Do not invent a resolved version.884. **Choose the narrowest correct repair.** When fixes are requested, correct an absent direct dependency,89 wrong scope/configuration, mistaken management entry, plugin dependency or90 toolchain selection according to the evidence. Respect an intentional platform91 version family. A targeted management override or constraint needs a compatibility92 reason and a check; a global force, transitivity disable or broad exclusion is93 not a default conflict fix. Do not upgrade unrelated dependencies.945. **Verify the causal path.** For an implemented change, compare the relevant graph before/after, rerun the95 failing task and an affected test or launch check. Check that requested tests96 actually ran; success with zero tests or an up-to-date task is not fresh execution.97 If a changed library is published, inspect generated consumer metadata and use98 a separate consumer when that contract is in scope. Do not claim a runtime fix99 from compilation alone.100101## Decision rules102103- **Managed but absent:** first establish an actual dependency path. Add a dependency104 only to the module/configuration that needs it; changing the BOM version cannot105 supply an artifact that is never included.106- **Conflicting versions:** use the build tool's selection evidence. Maven's nearest107 definition and Gradle's ordinary highest eligible version selection are different108 rules, both affected by explicit management/constraints. Neither proves binary or109 behavioral compatibility.110- **Exclusion proposed:** identify the introducing edge, the feature losing that111 artifact and any alternate path that still includes it. Exercise that feature or112 replacement. An exclusion removes an edge; it does not repair incompatible APIs.113- **Compile succeeds, runtime fails:** examine runtime inclusion, packaging and the114 deployed JVM. Test dependencies, provided/compile-only APIs and a newer dependency's115 bytecode are concrete hypotheses. If artifacts and versions are correct but loader116 behavior remains in question, retain the evidence for the class-loading handoff.117- **Generated code is missing:** identify the generator/processor and failing source set.118 Inspect its execution path, compiler options and generated-output registration before119 adding an application dependency. Annotation APIs, processor implementations, generated120 output and runtime support have different classpath roles; one does not imply the others.121- **Local succeeds, CI fails:** compare wrapper, profiles/properties, toolchains,122 repository/mirror access, selected versions and bytes before clearing anything.123 Avoid deleting shared caches or using refresh/update flags until there is a cache124 hypothesis; preserve the failing evidence and refresh narrowly when justified.125- **Locked therefore reproducible:** identify configurations covered by lock state,126 mutable artifacts, verification policy and actual outputs compared. A same-version127 SNAPSHOT can have different bytes. Keep version repeatability, artifact integrity128 and byte-for-byte build reproducibility as separate claims.129130## Minimum result131132For a small fix, a short explanation and diff are enough. Include the failing target,133evidence for the selected dependency/toolchain, causal explanation or remaining134hypothesis, scoped change, and checks actually executed. Name unavailable evidence135and the next check explicitly. A diagnosis or review finishes with supported findings,136their consequences, a scoped proposed correction and verification still needed; it137does not require a patch or claim an unexecuted repair succeeded.138139For a repair, stop when the original failure is addressed and the140affected behavior is verified, or when a material external gap has a concrete141resolving action. Do not turn the repair into a build-system migration.