git:20260930.effd2e3 to git:20261001.8dd87c9

---

name: sonar-lessons

description: >

Runs this project's SonarQube analysis, extracts the quality gate, bugs,

vulnerabilities, code smells, duplication and coverage through the SonarQube Web API,

traces every group of findings to the norm, template or Checkstyle setting in `.claude/`

that produced it, and writes `docs/lessons-learned/sonar-NNN.md` focused on fixing the

Explicit invocation only.

disable-model-invocation: true

model: opus

effort: high

---

# Sonar Lessons

Turns one SonarQube analysis into a lesson the **meta-repository** can act on. A Sonar

issue in a generated project is almost never a one-off: the code came from a template, a

norm allowed it, or nothing in `.claude/` said anything and the model decided alone. Fixing

it here fixes one project; fixing the owner fixes every project generated afterwards. This

repository that owns it.

**Entry rule: this skill runs the analysis, it never sets it up.** No scanner in the root

build file, no server answering, no token — stop and say which one, and what fixes it. It

writes nothing outside `docs/lessons-learned/`: not the build file, not the compose file,

not the token.

## Why this is a skill (Form 2) and not an agent

long prompt pasted into every feature round to produce a Sonar lessons-learned by hand. The

closest rejected form was the same skill plus a `sonnet` collector agent holding the build

log and raw JSON; it failed the counter-test of invariant 5, since `facets` and small pages

already keep the extraction short. Record: `@.claude/decisions/0100-sonar-lessons-skill.md`.

Runs on `opus`: step 4 — deciding which norm or template owns a finding, and what the fix

at the owner is — is the judgment the hand-written lessons-learned needed.

## Procedure

Endpoints, parameters and response fields of every call below:

`references/sonar-web-api.md`. Every `curl` authenticates with `-u "$SONAR_TOKEN:"` and

never prints the variable.

### 1 · Preconditions — stop on the first that fails

1. Root build file: `pom.xml` → maven, `build.gradle` → gradle. Neither → stop: nothing to

analyze (this is also what happens when the skill is typed in the claude-spring-architect

repository itself).

2. Scanner declared — `sonar-maven-plugin` / `org.sonarqube` in that file. Absent → stop:

"run `/sonarqube-setup` first".

3. `sonar.host.url` and `sonar.projectKey` read from the build file (`sonar.organization`

too, for SonarCloud).

4. `curl -sS <host>/api/system/status` answers `"status":"UP"`. Connection refused on

`localhost` → stop: "`docker compose up -d sonarqube`, wait for `UP`, re-run". Any other

host → stop, naming the host.

5. `SONAR_TOKEN` set and valid — `curl -sS -u "$SONAR_TOKEN:" <host>/api/authentication/validate`

answers `"valid":true`. Unset or invalid → stop, naming the variable. Browse permission

is only proven by the first read of step 3, and a 401/403 there stops the same way.

### 2 · Run the analysis

| Tool | Command |

|---|---|

| maven | `./mvnw -B -q verify sonar:sonar` |

| gradle | `./gradlew -q build sonar` |

`-q` rather than a redirect to a log file: the output stays short, and a redirect is a

write outside this skill's territory. A red build stops here — report the failing module

and the first error line; a lessons-learned about an analysis that never ran is fiction.

The analysis is **asynchronous**. Read `ceTaskId` from `target/sonar/report-task.txt`

(`build/sonar/report-task.txt` for gradle) and poll `/api/ce/task?id=<ceTaskId>` until

`SUCCESS`. Reading measures before that returns the **previous** analysis, silently.

`FAILED` or `CANCELED` → stop with the task's `errorMessage`.

### 3 · Extract

In this order, all read-only:

1. **Quality gate** — status and every condition, with its threshold and actual value.

2. **Measures** — the list in the reference: bugs, vulnerabilities, code smells, hotspots,

coverage, duplication, ratings, `ncloc`, and the `new_*` metrics the gate reads.

3. **Issues by rule** — one call with `ps=1` and facets on rules, software qualities,

severities and scopes: the counts, without paging through every issue. Then, for each

rule, one call with a small `ps` for sample locations, split `MAIN` / `TEST`.

4. **Rule text** — `/api/rules/show` for each rule key: its name and why it matters.

5. **Duplication** — files with duplicated blocks, then the blocks of each.

6. **Coverage** — the files with the most uncovered lines.

Large answers are the only real cost of this skill: always request the facet first and

page only what step 4 needs.

### 4 · Trace each finding group to its owner

Group by Sonar rule (a duplicated block is its own group). For each group, find the piece

of **this project's `.claude/`** that produced it, in this order, and stop at the first hit:

| Origin | How to find it |

|---|---|

| **Template copied verbatim** | `Grep` the flagged construct in `.claude/skills/*/templates/*.example`. A hit means every project gets the issue |

| **Norm that allows or requires it** | `.claude/rules/00-index.md` → the norm for that layer; a norm that prescribes the flagged shape, or explicitly permits it |

| **Checkstyle / build configuration** | `config/checkstyle/*.xml` and the root build file — a check that is missing, or disabled, where Sonar has the equivalent rule |

| **Test template teaches the pattern** | Same as the first row, restricted to `test-architect` and `new-feature` test templates |

| **Code the bootstrap generated** | No template in the project — `project-bootstrap` does not travel. Name it `project-bootstrap` plus the role of the file (entry point, exception handler, config class) |

| **Nothing — the model decided alone** | No norm and no template covers the construct. The fix is a norm, or a line in the one that owns that layer |

Then decide the **fix at the owner**: which file in `.claude/`, what change, and whether it

also needs enforcement (a Checkstyle check, an ArchUnit rule) so the issue cannot come back.

Say it concretely — a file path, a line, the shape of the change — never "improve the

template".

Check whether an owner file was edited locally since the export:

`java .claude/hooks/ArchHook.java doctor` names the edited `.claude/` files. When the file at

fault is one of them, the lesson says so: the meta-repository's version may not have the defect.

### 5 · Write `docs/lessons-learned/sonar-NNN.md`

`NNN` is the highest existing `sonar-*.md` plus one, `001` when the directory is empty.

Fill `templates/lessons-learned.md.example`: snapshot, issues by origin, one section per

group, and the structural lesson — what in `.claude/` would have caught the whole class of

issue before the analysis did. Complete here: project paths, lines, excerpts all belong in

this file.

**Progress against the previous run.** When `sonar-<NNN-1>.md` exists, read its snapshot

and fill the snapshot's *Previous* and *Δ* columns, and mark each finding group *new*,

*recurring* (same rule key in the previous file) or — in a closing list — *gone*. The goal

is fewer issues each round; this is the only place that says whether it is happening. A

recurring group whose previous file already named the fix at the owner says so: the fix was

proposed and has not reached this project (not merged upstream, or not pulled with

`/arch-adopt`).

Report the path and the snapshot line, then go on to step 6.

## Failure modes

**No scanner in the build file:**

```

❌ pom.xml declares no sonar-maven-plugin. Run /sonarqube-setup, then /sonar-lessons.

Nothing written.

```

**Server down:**

```

❌ http://localhost:9000 refused the connection.

Run `docker compose up -d sonarqube`, wait for /api/system/status to answer UP, re-run.

```

**Token missing, invalid, or unable to read:**

```

❌ SONAR_TOKEN is not set — export a user token (My Account → Security) and re-run.

❌ /api/issues/search answered 403 — SONAR_TOKEN can analyze but not browse this project.

A project analysis token cannot read the Web API; use a user token with Browse.

```

**Build red:**

```

❌ verify failed in <module> — <first error line>. No analysis ran; nothing written.

```

**Compute engine task failed:**

```

❌ Analysis task <id> ended FAILED: <errorMessage>. The previous analysis is still on the

server; nothing was read from it.

```

## Report

```

✅ Sonar lessons — <quality gate status> · <N> issues (<main> main / <test> test) · coverage <x> % · duplication <y> %

Lessons ..... docs/lessons-learned/sonar-NNN.md — <G> groups: <t> template, <r> norm, <c> checkstyle, <b> bootstrap, <m> model alone

Top owners .. <.claude path> (<n> issues) · <.claude path> (<n>) · …

Dashboard ... <host>/dashboard?id=<projectKey>

```

## Contract

**Class:** report — the territory is `skill_classes.report` in

`@.claude/schemas/extensions.json`: `docs/lessons-learned/**`, nothing else. `ArchHook.java

guard` enforces it; `target/` and `build/`, which the analysis writes, are ignored by git

and outside what `guard sweep` sees.

**Reads** the root build file, `target/sonar/report-task.txt` (or `build/sonar/`),

`.claude/rules/**`, `.claude/skills/*/templates/**`, `config/checkstyle/**`,

**Never writes** the build file, `docker-compose.yml`, a token, or anything under `src/`. A

finding is fixed at its owner in the meta-repository, or by `/new-feature` in this

project — not by this skill.

**Not chained** by any skill. Travels into the generated project

(`export.skills.include`); in the claude-spring-architect repository itself it stops at

step 1, which has no build file.