# Design: Gradle Build Doctor (Knowledge-Driven, Embedded Corpus, Lean)

## Overview

The Gradle Build Doctor is an embedded build-health-assessment workflow inside `authoring-gradle-builds`. It assesses a build **primarily by reading its files and applying the skill's own knowledge — first and foremost the embedded best-practice docs** (`references/best-practices/_index.md` with area sections and Browse-by-Tag, plus area pages) — orienting on the wrapper version and project shape, then systematically reading and applying the embedded best-practices corpus (PRIMARY), this skill's `SKILL.md` and references including `references/upgrading-and-release-notes.md` (SECONDARY), and `gradle_docs` (SUPPLEMENT). A small set of cheap assessment commands may be run only where static reading cannot produce the evidence, as ordinary workflow steps using existing MCP tools. The workflow reports prioritized, advisory findings summary-first and proposes fixes applied through the existing authoring workflows with explicit user approval. Zero new MCP tools, zero new skills; the doctor reads the embedded corpus, never edits it.

This design records the final workflow shape after the session's iterative revisions: knowledge-driven (no authored check catalog), static-first, exactly one reference file, exactly one capability delta, propose-only remediation, and minimal SKILL.md edits. Machinery accumulated in earlier revisions (enumerated check catalogs, precise probe evidence contracts, routing override clauses, heavier content gates) was superseded and is not part of the final workflow.

## Goals / Non-Goals

**Goals:**
- Embed as `### Build Health Assessment (Doctor)` inside `authoring-gradle-builds`, replacing `### Performance Audit` in place (same `## Workflows` slot, trigger retained, no second performance workflow), with exactly one authored reference carrying the procedure and report material.
- **Rely on the skill's knowledge — embedded corpus as PRIMARY**: the `references/best-practices/` corpus (`_index.md` + area pages) is the **PRIMARY** source the doctor reads and applies systematically (area sections + Browse-by-Tag); this skill's `SKILL.md` + references (incl. `references/upgrading-and-release-notes.md`) cover doctrine/deprecations; `gradle_docs` supplements with authoritative/current/version-appropriate guidance. The knowledge hierarchy is defined in exactly one place (the reference's `### Knowledge sources`) and deferred to via `#knowledge-sources` links everywhere else. The design does not re-author any of them as a check catalog.
- **Static-first**: the majority of findings come from reading files and applying doctrine; minimal probes supplement only where static cannot produce evidence, as ordinary workflow steps.
- Specify the reference **at section level** — each section's purpose and workflow-level instructions (what to read, which knowledge sources to apply, how findings are recorded, report shape, remediation) — enough to author the file without further design decisions, without enumerating checks.
- Reuse existing MCP evidence channels directly (`gradle`, `inspect_dependencies`, `gradle_docs`, `query_build`) — no new surface, no skill-imposed gates.
- Findings are proposals; remediation requires explicit user approval.

**Non-Goals:**
- No new skill directory, no inventory/docs changes (`DESCRIPTIONS`, `docs/skills.md`, `SkillToolsTest` untouched — five-name inventory stays).
- No new MCP tools/prompts/resources in v1.
- No edits to the embedded corpus or to the tooling that produces it (the doctor reads the corpus, never edits it).
- No silent auto-fix, no full build/test execution as diagnosis, no Build Scan `--scan` by default.
- No authored check catalog with IDs/grammars, no mode/severity grammars beyond `high/medium/low/info`, no matrices or fixtures, no precise probe evidence contracts, no execution-boundary or consent-gate machinery.

## Decisions

| ID | Decision | Rationale |
|----|----------|-----------|
| D1 | Embed in `authoring-gradle-builds` as `### Build Health Assessment (Doctor)` | User directive; keeps assessment next to remediation. |
| D2 | No new MCP tools/prompts/resources in v1 | All needed evidence already available via `gradle`, `inspect_dependencies`, `gradle_docs`, `query_build`. |
| D3 | Rely on the skill's knowledge — **embedded corpus as PRIMARY to read and apply**, not an authored check catalog | The `references/best-practices/` corpus (`_index.md` with area sections + Browse-by-Tag, plus area pages) is the PRIMARY source the doctor systematically reads and applies ("review the build against the embedded best-practice docs"); `gradle_docs` = authoritative/current SUPPLEMENT; this skill's `SKILL.md` + references (incl. `references/upgrading-and-release-notes.md`) = SECONDARY doctrine/deprecation coverage. The hierarchy is defined in exactly one place (the reference's `### Knowledge sources`) and deferred to via `#knowledge-sources` links. Duplication drifts and over-specifies; a pointer plus "apply what is relevant" with agent judgment is leaner and stays fresh. |
| D4 | Static-first, knowledge-driven: primary evidence is file reads + doctrine application; minimal probes are ordinary workflow steps only where static cannot produce evidence | Skills execute nothing; most health signals are visible statically; the workflow relies on knowledge, not precise goals. |
| D5 | Propose, don't auto-apply; prioritized recommendations | Applying edits remains an authoring action with user approval. |
| D6 | Version-aware: read `gradle/wrapper/gradle-wrapper.properties` first, note wrapper major; corpus-freshness note → `gradle_docs` for current guidance | Prevents wrong-version advice; the embedded corpus may not cover a newer wrapper major. |
| D7 | In-conversation, summary-first report; file output only on request | Matches existing skill UX. |
| D8 | Replace `### Performance Audit` in place; retain its trigger | Binding directive; audit intents are covered by the knowledge sweep. |
| D9 | Reference specified at section level: orientation file list, knowledge sources to apply, minimal functional probes, findings/report/remediation shapes | Satisfies the implementation-ready directive without reintroducing catalog/contract machinery. |

## Workflow Topology

`Orient → Knowledge-driven assessment (primary: read files + read and apply the embedded best-practices corpus) → Minimal probes (only where static cannot decide) → Finalize findings → Report (summary-first) → Propose fixes (with approval)`

| Phase | What the agent does | Evidence |
|-------|---------------------|----------|
| 1. Orient | Read `gradle/wrapper/gradle-wrapper.properties` (note wrapper major for version-sensitive advice), `settings.gradle(.kts)` (either DSL), `gradle/libs.versions.toml` if present, `gradle.properties`, and the module layout (directories with `build.gradle(.kts)`; note `buildSrc/`, `build-logic/`, `gradle/plugins/` if present). Absent optional files are project shape, not findings. | File reads |
| 2. Knowledge-driven assessment — primary | **Systematically read and apply the embedded `references/best-practices/` corpus as the PRIMARY source** — entry point `references/best-practices/_index.md` (area sections + Browse-by-Tag cross-reference) then area pages on demand. Review the build's files **against the embedded best-practice docs** area by area, applying what is relevant with the agent's Gradle/build knowledge. Supplement with `gradle_docs` for authoritative/current/version-appropriate guidance (including migration guides and release notes for the wrapper's version) and with this skill's references (incl. `references/upgrading-and-release-notes.md`) per the `### Knowledge sources` hierarchy. The workflow does not enumerate checks; record findings as they emerge using the advisory shape (type, area, severity, evidence tag, why with doctrine pointer, recommendation). | File reads + **embedded corpus (`_index.md` + area pages)** / skill references / `gradle_docs` (SUPPLEMENT) |
| 3. Minimal probes — supplementary | Only where static reading cannot decide (e.g., whether a deprecated API is actually exercised, whether configuration cache is compatible for a given task, version-health or plugin-posture questions, what the last-known build problems were), run the small set of cheap assessment commands as ordinary workflow steps (see Reference Content Specification). Probes surface observable signals only; they never verify build task outputs or artifacts. Probes are skipped when not needed; probe failures are diagnostic input ("probe unavailable/failed — assessed from static files"), never guessed results. | `gradle`, `inspect_dependencies`, `query_build`, `gradle_docs` (only when needed) |
| 4. Finalize findings | Merge static + probe evidence; deduplicate; assign type/severity/evidence tag and optional confidence; prioritize. | — |
| 5. Report | In-conversation, summary-first: the report format is defined first (header with title + wrapper version + scope note listing which tools/probes were available, ran, or were skipped and the corpus-freshness note; severity counts + prioritized recommendations 0–5 with per-class totals; findings grouped A. Build Script Errors → B. Forward-Compat & Risks → C. Recommendations → D. Healthy Areas, within A/B/C grouped by area), then examples illustrating the classes. Each finding: type, area, severity (calibrated per type — forward-compat `high` only if removal lands in the next Gradle major, labeled e.g. `Future Breakage (Gradle 10)`), evidence tag (`direct`/`observed`/`web`), why (one-line + doctrine pointer), Fix/Consider/Risk, optional confidence. Label any probe that was unavailable/failed/skipped. | — |
| 6. Propose fixes | Prioritized proposal list, propose-only by default. Apply only after explicit approval, through this skill's authoring workflows (dependency-deep work via the existing handoff). Re-check each fix the cheapest way (re-read files or re-run the same probe) before marking resolved. | — |

**Performance Audit subsumption**: the audit intents (eager APIs, provider realization, config-phase resolution, cross-project coupling, configuration-cache violations, build-cache/parallel posture, measure-first guidance) are covered by the knowledge-driven review plus minimal probes; the `### Performance Audit` workflow is deleted and the doctor occupies its slot.

## Skill Content Layout

### SKILL.md edits (minimal — four edits)

1. **Frontmatter `description` — Positive Triggers**: add assessment phrasing ("Assessing build health, running best-practice audits, or handling Gradle doctor / build health check / performance audit requests.") and retain the Performance Audit trigger coverage ("Modifying advanced Gradle configuration and build performance settings."). No `DESCRIPTIONS` or `UpdateSkills.kt` change needed.
2. **Decision Routing table**: add one row — assessment / health check / doctor → `[Build Health Assessment](references/build-health-assessment.md)`.
3. **`## Workflows` — replace `### Performance Audit` in place**: replace `### Performance Audit` in place with `### Build Health Assessment (Doctor)` occupying the same position after `### Add Dependency` (so `## Workflows` stays three entries). The new section is a lean pointer: when to use (build health checks, best-practice audits, Gradle doctor / build health check / performance audit requests); load `references/build-health-assessment.md` as the single authoritative procedure (it carries both the assessment steps and the report material); its `#knowledge-sources` hierarchy governs the assessment and is not restated in the body. No check catalog, no probe catalog, no packaging vocabulary in SKILL.md.
4. **Version bump** — `metadata.version` `1.4.0 → 1.5.0`.

No per-statement exception clauses, no override-routing machinery, no routing-reconciliation tables.

### Authored doctor reference (exactly one file) — section-level specification

**New file (exactly one, fixed name)**: `src/main/skills/authoring-gradle-builds/references/build-health-assessment.md` — the sole canonical path; no alternative filename, no two-file split. `zipSkills` includes it automatically; no build-script change. The reference SHALL be authored with the sections below; it SHALL NOT enumerate a check catalog and SHALL NOT define precise probe evidence contracts or scope clauses.

1. **Frontmatter and purpose** — H1 title; one-paragraph 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 (checked via file/path existence, never by running tasks); minimal probes surface observable signals only where static reading is insufficient; findings are advisory and reported summary-first; fixes are proposed and applied only with explicit user approval; the assessment does not verify build task outputs or artifacts. "When to use" bullets (health checks, best-practice audits, pre-migration audits, CI hygiene passes, performance audits). **`### Knowledge sources` section (single authoritative hierarchy definition, deferred to via `#knowledge-sources` links everywhere else)**: PRIMARY = [Embedded best-practices corpus](best-practices/_index.md) — the PRIMARY source the doctor systematically reads and applies (`references/best-practices/_index.md` area summaries and Browse-by-Tag → area pages); SECONDARY = this skill — `SKILL.md` (already read when this workflow loads) and its references, consulted per area without re-listing their contents, with migration guides and release notes in `references/upgrading-and-release-notes.md`; SUPPLEMENT = `gradle_docs` — authoritative/current version-specific detail, including the migration guides and release notes for the wrapper's version, e.g. `gradle_docs(path="userguide/upgrading_version_<N>.md")` and `gradle_docs(query="tag:release-notes")`. The embedded corpus is read-only and must not be edited. Zero packaging/implementation vocabulary about the corpus.
2. **Orientation — which files to read, how to note project shape** — read in order: `gradle/wrapper/gradle-wrapper.properties` (required; note wrapper major for version-sensitive advice); `settings.gradle(.kts)` (either DSL; read `pluginManagement`, `dependencyResolutionManagement`, `include(...)` module list); `gradle/libs.versions.toml` (if present, note catalog entries; if absent, note project shape — not a finding); `gradle.properties` (note caching/parallel/CC flags); module layout (enumerate directories containing `build.gradle(.kts)`; note `buildSrc/`, `build-logic/`, `gradle/plugins/` if present); per module, note applied plugins and publishing/testing wiring for conditional relevance. Orientation notes shape without emitting findings; findings come from the assessment step.
3. **Knowledge-driven assessment — what to do (no check catalog)** — as the PRIMARY assessment step: **systematically read and apply the embedded best-practice docs** and review the build against them, using the agent's Gradle/build knowledge to determine what applies: **PRIMARY source the doctor READS and APPLIES** — the embedded `references/best-practices/` corpus, entry point `references/best-practices/_index.md` (area sections + Browse-by-Tag cross-reference) then area pages on demand; walk the corpus — start at `_index.md` to survey area summaries and the Browse-by-Tag cross-reference, then read the relevant area pages and **review the build's files against each area/tag that applies**. Then the supplementary sources with their distinct roles per `### Knowledge sources`: **`gradle_docs`** — authoritative/current/version-appropriate supplementation (including wrapper-version migration guides and release notes), used to confirm or update what the embedded corpus says, especially when the wrapper is newer than the corpus — not a substitute for reading the embedded docs; **this skill's `SKILL.md` and references** (incl. `references/upgrading-and-release-notes.md` for migration guides, release notes, and deprecations) consulted per area. Describe the sweep by build area (e.g., structure/settings, build logic, dependencies, performance/caching, reproducibility/upgrading — headings, not a normative list) without enumerating precise checks. For each potential issue, record a finding per the findings shape with a doctrine pointer (embedded-corpus entry via `_index.md`/area page, skill reference, upgrading-notes section, or `gradle_docs` path) as the rationale. Include the **corpus-freshness** instruction (if the wrapper major is newer than the corpus coverage, add a freshness note to the report and treat `gradle_docs` as authoritative for that area — without skipping the embedded-corpus review), guidance that absent optional files and single-module layouts are project shape not findings unless context makes them relevant, and a brief "how to apply" note (read the build files, then for each corpus area/tag that is relevant check whether the build follows the embedded practice; where context is ambiguous, use `gradle_docs` or a minimal probe to confirm — still no check catalog).
4. **Minimal probes — functional guidance (only where static insufficient)** — describe the small set of cheap assessment commands the workflow may run **only where static reading cannot produce the evidence**, as ordinary workflow steps using existing MCP tools, functionally and briefly (which tool/command, when it is useful — no exact evidence contracts or scope clauses): **deprecation warnings** — `gradle help --warning-mode all` (or `tasks --warning-mode all`) via the `gradle` tool, to confirm deprecated APIs are exercised (probe-surfaced deprecations are captured, recorded as Future Breakage findings, and highlighted in the report; findings from this probe tagged `observed`); **wrapper version** — `gradle --version` or the wrapper properties already read during orientation (static signal for version-sensitive advice); **configuration-cache compatibility** — `gradle help --configuration-cache` via the `gradle` tool, when static reading suggests CC-relevant patterns or the user asked about CC for a non-trivial build; **dependency/plugin audit** — `inspect_dependencies`, when version-health or plugin-posture support would strengthen a recommendation (when unavailable, continue with static evidence); **last-known build problems** — `query_build`/Problems API from a prior `gradle` invocation, as passive evidence when a recent build exists (do not trigger a new build solely for this). Include a brief boundary note: probes are optional, run only when the open question matters for a finding or claim, surface observable signals only (never verify build task outputs or artifacts), and failures are recorded as "probe unavailable/failed — assessed from static files" without guessing; the report header lists which tools/probes were available, ran, or were skipped so silent degradation (e.g., absent `inspect_dependencies` or `gradle_docs`) stays transparent; `gradle_docs` tag queries are doc lookups, not probes, and may be used throughout.
5. **Findings recording, report template, and remediation + scope boundaries** — findings as advisory blocks (type, area, severity, evidence tag, why with doctrine pointer, Fix/Consider/Risk, optional confidence; short markdown examples AFTER the report format is defined; no schema enforcement); a copyable report template — (1) header: title + wrapper version + scope note (what was/wasn't probed + corpus-freshness note), (2) summary: severity counts + prioritized recommendations (0–5, supported by evidence, not manufactured) with per-class totals (e.g., "0 errors; 2 recommendations in Dependencies" for a repo with zero incidental errors but stale deps), (3) findings grouped by class in strict order A. Build Script Errors → B. Forward-Compat & Risks → C. Recommendations → D. Healthy Areas, within A/B/C grouped by area, (4) optional evidence note (which probes ran/failed/skipped with `direct`/`observed`/`web` tags), (5) next-step proposal with an explicit approval prompt ("Shall I apply <fix> via <workflow>?"); file output only on user request. **Finding taxonomy**: `Build script errors / mistakes` (incidental; `Fix:` directive; always `high` when present; expected to be empty — this is not a build-implementation audit and not a full code review of the build logic) vs `Best practice / recommendation compliance` (sub-types `Future Breakage` / `Risk` / `Recommendation`; `Consider:` / `Risk:` framing); severity calibrated per type — `Future Breakage` `high` only if removal lands in the next Gradle major per the upgrading/release-notes references else `medium`, labeled `Future Breakage (Gradle 10)` with deprecation-since evidence; `Risk` `high` if prod-facing or widening blast radius else `medium`; `Recommendation` `medium`/`low`/`info` by impact; evidence tagged `direct` / `observed` / `web`. **Remediation**: propose-only — applying edits requires explicit approval per fix; edits go through this skill's authoring workflows; dependency-deep work via the existing `advanced-gradle-dependencies` handoff; re-check after apply via the cheapest evidence (re-read files or re-run the same probe). **Scope boundaries**: exactly one doctor reference file (procedure AND report; no split); no new MCP tools; no full build/test execution as diagnosis; no `--scan` by default; probes limited to observable signals; absent optional files are project shape, not findings, unless context makes them relevant.

**One-reference binding (strict)**: implementation is bound to **exactly one** doctor reference file at `src/main/skills/authoring-gradle-builds/references/build-health-assessment.md` containing **both** the procedure and the report material. No split into two files is permitted, and no second file under `authoring-gradle-builds/references/` fulfills the doctor's role.

### Edits to other skills

None. `using-gradle`, `advanced-gradle-dependencies`, and other skills are not edited (no delta, no probe contract outside `authoring-gradle-builds`). No inventory or docs wiring changes (`DESCRIPTIONS`, `docs/skills.md`, `SkillToolsTest` untouched; five-name inventory unchanged).

## Capability Deltas

**Exactly one capability delta**:

- `specs/authoring-gradle-builds/spec.md` — MODIFIED + ADDED.

No `using-gradle`, `gradle-build-doctor`, `skill-infrastructure`, or `skill-metadata` deltas; `specs/using-gradle/spec.md` is absent from the change.

- The MODIFIED `Requirement: Modification Index` is a **complete replacement** retaining all of its own base text and existing scenarios verbatim, plus **minimal doctor additions** phrased as positive workflow SHALLs: the Build Health Assessment workflow is available as `### Build Health Assessment (Doctor)`, replaces `### Performance Audit` in place as the sole build-health/performance assessment workflow, and is bound to exactly one reference, `references/build-health-assessment.md`. It is **not** an override-routing clause and transplants no other requirement's text or scenarios.
- The ADDED requirements encode: the **knowledge-driven workflow** (assess the build against the skill's embedded knowledge sources — the embedded best-practices corpus as PRIMARY read/apply source (`references/best-practices/_index.md`), this skill as SECONDARY (incl. `references/upgrading-and-release-notes.md`), `gradle_docs` as SUPPLEMENT; the hierarchy defined in exactly one place (the reference's `### Knowledge sources`) and deferred to via `#knowledge-sources` links; minimal probes as ordinary steps only where static cannot decide; no authored check catalog, no precise probe contracts), the **advisory summary-first findings/report model** (type/area/severity/evidence/recommendation with doctrine pointer; report format defined before examples; classes A–D; severity counts + prioritized recommendations 0–5, not manufactured; corpus-freshness note), and **propose-only consented remediation** (explicit approval per fix; applied via this skill's authoring workflows; exactly one reference; no second performance workflow).
- Requirement-name parity with the base spec: the MODIFIED requirement keeps the base spec's exact name (`Requirement: Modification Index`); ADDED requirement names are stable across proposal/spec/tasks.

## Verification

- **Change shape**: `openspec validate add-gradle-build-doctor --strict` passes; exactly one capability delta (`authoring-gradle-builds`); `specs/using-gradle/spec.md` absent.
- **Lightweight content gate** (`AuthoringDoctorContentTest`): (1) `src/main/skills/authoring-gradle-builds/SKILL.md` contains the `### Build Health Assessment` heading **and** links the exact path `references/build-health-assessment.md`; (2) `### Performance Audit` is absent from `SKILL.md`; (3) `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; (4) exactly one doctor reference file at the fixed path (no second `doctor*.md` split); (5) the reference names migration guides and release notes as sources (`references/upgrading-and-release-notes.md`, `gradle_docs(query="tag:release-notes")`); (6) the reference instructs recording and highlighting probe-surfaced deprecations (`gradle help --warning-mode all`, "record it as a finding", "highlight it in the report"); (7) 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:`); (8) the reference defines evidence tags `` `direct` `` / `` `observed` `` / `` `web` ``; (9) the reference states it is "not a full code review of the build logic"; (10) the reference calibrates forward-compat severity ("High only if removal lands in the next Gradle major", "Future Breakage (Gradle 10)"). The embedded corpus file `references/best-practices/_index.md` is not authored content of this change; its absence from the source tree is expected and SHALL NOT be treated as a defect.
- **Unit**: `./gradlew test` passes.

No assertion requires enumerated check catalogs, per-check doctrine bindings, precise probe evidence contracts or scope-contract text, override-routing clauses, or per-statement routing exception counts. The gate is intentionally minimal.

## Risks / Trade-offs

| Risk | Mitigation |
|------|-------------|
| Knowledge-driven assessment feels vague vs. a pinned catalog | Reference specifies sections + workflow-level instructions and the exact knowledge sources to apply (embedded corpus as PRIMARY); the agent's Gradle knowledge plus `gradle_docs` keeps advice current without re-encoding the corpus. Reviewers can tighten prose without adding a catalog. |
| Wrapper-version skew / corpus staleness | Orient reads wrapper first + corpus-freshness note; `gradle_docs` is version-scoped and authoritative, but the embedded corpus is still read and applied. |
| Audit intent lost in replacement | Audit intents are covered by the knowledge sweep — the corpus and skill references already encode them; the reference's systematic review applies them. |
| Over-adding reference files later | Design caps the shape at one file; a second file needs explicit justification — default is to extend the single file. |
| Static false positives without precise checks | Findings are advisory with evidence + doctrine pointer; probes are available where static cannot decide, but not required to be exhaustive. |

## Open Questions

None. No blocking decisions remain: the filename is fixed (`references/build-health-assessment.md`, exactly one file), the workflow shape is settled (static-first, knowledge-driven with the embedded best-practices corpus as PRIMARY read/apply source, minimal probes as ordinary steps), and the SKILL.md edit set is minimal (four edits). If a new probe proves essential later, it can be added as a brief functional entry in the reference's probe section without changing this design.
