Report Issue

The single door from a generated project to the Nerviz repository. A defect in a template, a norm or a hook shows up here first, but its fix belongs upstream: fixing it in this project fixes one project, fixing the owner fixes every project generated afterwards. This skill writes the report so that the owner can act on it — and so that the maintainer, who verifies every claim before accepting it, can find each one.

Entry rule: only the user files. Nothing chains this skill. /sonar-lessons ends by printing the command that runs it; the user types it or doesn't.

Evidence rule: a report nobody can verify is not filed. The meta-repository triages every issue skeptically — each claim is checked against its own code before anything changes. A claim with no file, no output and no way to reproduce it can only be closed as needs evidence, so this skill asks for what's missing before it writes anything.

Privacy rule: the issue carries the trace, never the project. The Nerviz repository is public and this project may not be. The body names Sonar rule keys, counts, paths inside .claude/, commands and hook output only — never a path under src/, a package, a class name of this project, a code excerpt, the project key, a server URL, a hostname, or a credential. This skill is the only owner of that rule; every issue form's field descriptions repeat it per field.

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

Form 2 because publishing on a public repository is a side effect the model must not trigger on its own — axis 2 of the design interview: the user types /report-issue, nothing chains it. The closest rejected form was keeping sonar-lessons' own publish step and writing a second one here; two publishers would hold two copies of the privacy rule and the duplicate search, and the first to change would leave the other filing the old way (invariant 2). Record: @.claude/decisions/0103-issue-filing-and-skeptical-triage.md.

Runs on opus: deciding which form a free description fits, what evidence it lacks, and what in it identifies the project is the judgment this skill exists for.

Procedure

1 · Read the input

• A path under docs/lessons-learned/ → read the whole file. A sonar-NNN.md written by /sonar-lessons goes to the sonar-lessons form at step 3; any other file is classified there like a description.
• Free text → that is the description.
• Nothing → ask for one of the two, once, and stop without an answer.

2 · Target and version

1. Target — the slug from source.git_url in .claude/schemas/extensions.json (https://github.com/<owner>/<repo>.git → <owner>/<repo>).
2. Version — .claude/.arch-provenance.json gives ref, commit and blueprint. No stamp → stop: this is not a project generated or adopted from Nerviz, and the issue would have no version to be verified against.
3. Behind? — git ls-remote --tags --sort=-v:refname <git_url> and take the first tag. When ref is a tag and an older one, say so: the newer release may already carry the fix, and /arch-adopt pulls it. When ref is not a tag, compare commit with git ls-remote <git_url> HEAD. Behind is a warning carried into the question of step 6, not a stop — the defect may still be open upstream.

3 · Pick the form

Fetch the form the repository owns: curl -sS https://raw.githubusercontent.com/<owner>/<repo>/HEAD/.github/ISSUE_TEMPLATE/<form>.yml.

Input	Form
A sonar-NNN.md from /sonar-lessons	sonar-lessons.yml
Something in .claude/ behaves differently from what its own file says	bug_report.yml
Something is missing, repetitive or silently wrong, and no file promises otherwise	feature_request.yml

Ambiguous between bug and feature → ask, naming what tips each way. The form is the single owner of the title prefix (title:), labels (labels:), the sections and what each may carry — read all four from it, never from this file. No answer from the fetch → stop: no issue is written from memory of a form.

4 · Evidence — ask once for what's missing, then stop

What a maintainer needs to verify the report, by form:

Form	Required before writing
bug_report.yml	The entry point (command, skill, agent or hook mode) · the file in .claude/ that promises the expected behavior, quoted · the actual output, literal · steps to reproduce
feature_request.yml	One concrete occurrence of the problem — a run, an output, a file — not only the wish · what in .claude/ was expected to cover it, or "nothing does"
sonar-lessons.yml	Already in the file — /sonar-lessons wrote it. Skip this step

Read each item from the input first; for a bug, java .claude/hooks/ArchHook.java doctor fills the form's doctor field and often names the file at fault. Ask for every missing item in one AskUserQuestion. Still missing after the answer → stop, write nothing, and say which item would let the issue be verified. A guess written in the user's place is the claim the maintainer refutes first.

5 · Write the body

docs/lessons-learned/<name>.issue.md, where <name> is the input file's base name (sonar-NNN → sonar-NNN.issue.md), or issue-NNN for a description — NNN the highest existing issue-*.issue.md plus one, 001 when there is none.

One ### <label> heading per form field, in the form's order, filled from the input under that field's description — the same shape the web form produces. A markdown element has no label and is skipped; a checkboxes field is rendered as - [X] <option>, and only once the statement is true — the preflight boxes included: tick I searched the existing issues only after step 6's search ran. The Source version field, or the Environment field when the form has no version field, carries ref (short commit) · blueprint from step 2.

Then apply the privacy rule to every line, and re-read the file for src/, the project's base package, its group id, the project key, and any URL that is not github.com or a public documentation site. A hit is rewritten to the .claude/ owner or removed, and named in the question of step 6.

6 · Duplicates, then ask — nothing sent before the answer

1. gh auth status. Not authenticated → stop: the body file is the deliverable, and the report carries the command.
2. gh issue list -R <slug> --state open --search "<terms>" with the form's label, for the two or three most specific terms of the report — a Sonar rule key, a file name in .claude/, a hook mode.
3. Ask — the body file's path and its sections, the duplicates found, the version warning of step 2 if any, the privacy rewrites of step 5 if any, and three options: create the issue; I'll edit the body first — stop, and the report carries the gh issue create command to run after the edit; don't publish.

7 · Create, and record the outcome

On the first option only: gh issue create -R <slug> --title "<form title prefix><summary>" --label <form label> --body-file docs/lessons-learned/<name>.issue.md. A failure naming the label (no triage permission on that repository) → the same command once without --label.

When the input was a lessons-learned file, write the outcome in the ## Issue line at its end — the URL, declined, left for a manual edit (with the command), or not created — <reason>. Every path out of steps 3, 4, 6 and 7 writes it: the file is what a later reader, or the next /sonar-lessons run, checks to know whether the lesson reached the meta-repository.

Failure modes

No provenance stamp:

❌ .claude/.arch-provenance.json not found — this project was not generated or adopted from
Nerviz, so there is no version to report against. Nothing written.

Form not reachable:

❌ https://raw.githubusercontent.com/<slug>/HEAD/.github/ISSUE_TEMPLATE/<form>.yml did not answer.
No issue is written from memory of a form. Nothing written.

Evidence missing after asking:

❌ Not filed: the report has no <literal output | file in .claude/ that promises the behavior |
steps to reproduce>. The maintainer verifies every claim before acting on it; without this one
the issue can only be closed as "needs evidence". Nothing written.

gh not authenticated:

⚠️ docs/lessons-learned/<name>.issue.md written. Issue not created: gh is not authenticated —
run `gh auth login`, then:
gh issue create -R <slug> --title "<title>" --label <form label> --body-file docs/lessons-learned/<name>.issue.md

Privacy check hit:

⚠️ <name>.issue.md line <n> named <src/… | the base package | the project key | a host>.
Rewritten to the .claude/ owner before asking. Review the file before confirming.

Report

✅ Report issue — <form> · <source version> <· behind <latest tag>>

Body ........ docs/lessons-learned/<name>.issue.md
Duplicates .. <#N title | none open>
Issue ....... <URL | not created — <reason> | declined | left for a manual edit: <command>>

Contract

Class: report — the territory is skill_classes.report in @.claude/schemas/extensions.json: docs/lessons-learned/**, nothing else. ArchHook.java guard enforces it.

Reads the input file, .claude/schemas/extensions.json (source.git_url), .claude/.arch-provenance.json, the issue form fetched from the meta-repository's HEAD, and, for a bug, the .claude/ files the report names and ArchHook.java doctor's output.

Writes docs/lessons-learned/<name>.issue.md — the exact body that was, or would have been, published — and the ## Issue line of the input lessons-learned file.

Publishes one issue on the repository named by source.git_url, only after the confirmation of step 6, with the body file as it stands on disk.

Owns the privacy rule and the duplicate search for every issue this project sends upstream. /sonar-lessons hands its file here instead of publishing.

Does not own the issue's shape: the meta-repository's forms do — .github/ISSUE_TEMPLATE/bug_report.yml, .github/ISSUE_TEMPLATE/feature_request.yml and .github/ISSUE_TEMPLATE/sonar-lessons.yml, fetched at step 3. The web form and this skill produce the same issue because they read the same file; renaming one breaks this step in every project already exported, which is why CI checks that each path cited here exists.

Never writes anything under src/, the build file, a token, or a .claude/ file — a fix belongs to the meta-repository, pulled back with /arch-adopt.

Not chained by any skill. Travels into the generated project (export.skills.include); in the Nerviz repository itself it stops at step 2, which has no provenance stamp.