# Tasks: Add Gradle Build Doctor

## 1. Phase 1: Change Shape

- [x] **1.1 — Verify change shape and strict validation**: Confirm the change has exactly ONE capability delta — `specs/authoring-gradle-builds/spec.md` only — with `specs/using-gradle/spec.md` absent under the change dir; confirm the delta contains the MODIFIED `Requirement: Modification Index` (a complete replacement retaining all of its own base text and existing scenarios verbatim plus minimal doctor additions — no override-routing clause) and the ADDED knowledge-driven requirements (`Build Health Assessment Workflow`, `Doctor Findings and Report`, `Doctor Consented Remediation`); run `openspec validate add-gradle-build-doctor --strict` and confirm it passes.

## 2. Phase 2: Skill Content

- [x] **2.1 — Create the doctor reference**: Create `src/main/skills/authoring-gradle-builds/references/build-health-assessment.md` at that exact fixed path (exactly one file; no split, no alternative filename) per design §5.2 with the five sections: frontmatter and purpose (a knowledge-driven health assessment focused on best practices, build structure, linting, and forward-compat — not a full code review of the build logic; build-definition mistakes are incidental, statically-obvious observations only); a single authoritative `### Knowledge sources` section defining the hierarchy — PRIMARY = the embedded best-practices corpus (`references/best-practices/_index.md` area summaries + Browse-by-Tag → area pages, read and applied systematically), SECONDARY = this skill (`SKILL.md`, already read when the workflow loads, and its references consulted per area, including `references/upgrading-and-release-notes.md` for migration guides and release notes), SUPPLEMENT = `gradle_docs` (authoritative/current version-specific detail, including `gradle_docs(path="userguide/upgrading_version_<N>.md")` and `gradle_docs(query="tag:release-notes")` for the wrapper's version) — with every other section (and the SKILL.md doctor section and the spec) deferring via `#knowledge-sources` links and the corpus marked read-only, with zero packaging/implementation vocabulary about the corpus; orientation file list (required `gradle/wrapper/gradle-wrapper.properties`; optional `settings.gradle(.kts)`, `gradle/libs.versions.toml`, `gradle.properties`, module layout — absent optional files noted as project shape, not findings); knowledge-driven assessment (systematically read and apply the embedded best-practices corpus as PRIMARY — `best-practices/_index.md` area sections + Browse-by-Tag → area pages — reviewing the build against each applicable area/tag; no authored check catalog; corpus-freshness note when the corpus does not cover the wrapper version); minimal probes as ordinary workflow steps only where static reading cannot produce the evidence (`gradle help --warning-mode all` / `tasks --warning-mode all` for deprecation warnings, `gradle --version` for the wrapper version, `gradle help --configuration-cache` for configuration-cache compatibility, `inspect_dependencies` for version-health/plugin-posture support, `query_build` for last-known build problems) — surfacing observable signals only, never verifying build task outputs or artifacts, with probe-surfaced deprecations captured, recorded as findings, and highlighted in the report; findings/report/remediation (report format defined first, examples after; classes A. Build Script Errors → B. Forward-Compat & Risks → C. Recommendations → D. Healthy Areas; evidence tags `direct` / `observed` / `web`; `Fix:` / `Consider:` / `Risk:` directives; forward-compat severity `high` only if removal lands in the next Gradle major, labeled `Future Breakage (Gradle 10)`; propose-only remediation with explicit approval per fix, applied through this skill's authoring workflows, re-checked the cheapest way); and scope boundaries (exactly one reference; no new MCP tools; no full build/test execution as diagnosis; no `--scan` by default). The embedded corpus is READ, never edited.
- [x] **2.2 — Edit SKILL.md (four minimal edits)**: Edit `src/main/skills/authoring-gradle-builds/SKILL.md` with the minimal edit set: (1) frontmatter Positive Triggers reconciled — add assessment/health phrasing ("Assessing build health, running best-practice audits, or handling Gradle doctor / build health check / performance audit requests") and retain the performance trigger; (2) Decision Routing table — add one row for build health assessment / doctor → `[Build Health Assessment](references/build-health-assessment.md)`; (3) replace `### Performance Audit` in place with `### Build Health Assessment (Doctor)` (same `## Workflows` slot) as a lean pointer — when to use, load `references/build-health-assessment.md` as the single authoritative procedure carrying both the assessment steps and the report material, with its `#knowledge-sources` hierarchy governing the assessment and no re-narration of the knowledge hierarchy or probe catalog in the body; (4) bump `metadata.version` `1.4.0 → 1.5.0`. No exception clauses on other routing statements.

## 3. Phase 3: Verification

- [x] **3.1 — Add the minimal content-gate test and run it**: Add a lightweight content-gate test `AuthoringDoctorContentTest` under `src/test/kotlin/dev/rnett/gradle/mcp/skills/` asserting: (a) `src/main/skills/authoring-gradle-builds/SKILL.md` contains the `### Build Health Assessment` heading and links the exact path `references/build-health-assessment.md`; (b) `### Performance Audit` is absent from `SKILL.md`; (c) `src/main/skills/authoring-gradle-builds/references/build-health-assessment.md` exists and contains a pointer to the embedded best-practices corpus (`references/best-practices/_index.md`) as PRIMARY and a `gradle_docs` pointer; (d) exactly one doctor reference file at the fixed path (no second `doctor*.md` split); (e) the reference names migration guides and release notes (incl. `references/upgrading-and-release-notes.md` and `gradle_docs(query="tag:release-notes")`); (f) the reference instructs recording and highlighting probe-surfaced deprecations (`gradle help --warning-mode all`, "record it as a finding", "highlight it in the report"); (g) the reference defines the finding taxonomy and report classes (`Build script errors / mistakes`, `Best practice / recommendation compliance`, `Future Breakage`, `A. Build Script Errors`, `B. Forward-Compat`, `C. Recommendations`, `D. Healthy Areas`, `Fix:`, `Consider:`); (h) the reference defines evidence tags `` `direct` ``, `` `observed` ``, `` `web` ``; (i) the reference states it is "not a full code review of the build logic"; (j) the reference calibrates forward-compat severity ("High only if removal lands in the next Gradle major", "Future Breakage (Gradle 10)"). Do NOT assert the presence of `references/best-practices/_index.md` among the authored files (the corpus is embedded with the skill, not authored content of this repository). Run `./gradlew test` (or at minimum the content-gate suite) and confirm it passes.
- [x] **3.2 — Final strict validation**: Run `openspec validate add-gradle-build-doctor --strict` and confirm it passes with exactly one capability delta (`authoring-gradle-builds` only; no `using-gradle` delta).
