该技能用于在 Gradle 构建失败或异常时进行系统排查。适用场景包括：调试 OutOfMemoryError 或堆空间问题、解决依赖冲突与版本不匹配、修复构建缓存或配置缓存问题、诊断构建变慢、处理守护进程或 wrapper 问题、调试插件加载失败、排查 TestContainers 或 Docker 连通性问题，以及调查仅在 CI 出现而本地正常的测试失败。
基本用法是先用诊断命令定位问题，再按类别修复。构建失败时可依次执行：./gradlew --stop 与 ./gradlew clean；再用 ./gradlew build --stacktrace --info 获取详情；必要时用 --scan 生成构建扫描，或用 --profile 分析性能。提高日志详细度可用 --stacktrace、--full-stacktrace、--info、--debug，并配合 grep 过滤关键字。
内存问题时可临时用 ./gradlew build -Dorg.gradle.jvmargs="-Xmx8g"，持久方案是在 gradle.properties 中设置 org.gradle.jvmargs；修改后需执行 ./gradlew --stop 重启守护进程，并用 --info 过滤 XX:Xmx 验证。依赖问题可用 ./gradlew dependencies 查看依赖树、./gradlew dependencyInsight --dependency <名称> 定位来源，再通过 resolutionStrategy.force、exclude 或 constraints 解决，必要时用 --refresh-dependencies 重新下载。缓存问题可先用 --no-build-cache 或 --no-configuration-cache 验证，确认后清理 ~/.gradle/caches/build-cache-* 或整个 ~/.gradle/caches；配置缓存可用 --configuration-cache-problems=warn 起步，报告位于 build/reports/configuration-cache/ 下，修复后再切到 fail。
限制方面，资料未提供该技能的具体版本要求、收费方式、安装步骤及效果保证；部分高级排查（慢构建分析、守护进程管理、wrapper 问题、插件解析）指向 references/advanced-troubleshooting.md，详细示例另见 references/advanced-examples.md，完整命令参考见 references/commands-and-checklists.md。相关技能包括 gradle-testing-setup、gradle-performance-optimization、gradle-ci-cd-integration。