report-issue
Files an issue on the Nerviz repository from inside a generated project, from a description or a lessons-learned file, and refuses a report with no evidence a maintainer can verify.
report-issue, section by section
The sections of the skill's own SKILL.md, excerpted. Hover or click one to see which project rules, templates and references/ files it cites. The sections are also chips: click one to jump to it.
## 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.
### 1 · Read the input
- A path under
docs/lessons-learned/→ read the whole file. Asonar-NNN.mdwritten by - Free text → that is the description.
- Nothing → ask for one of the two, once, and stop without an answer.
### 2 · Target and version
- Target — the slug from
source.git_urlin.claude/schemas/extensions.json - Version —
.claude/.arch-provenance.jsongivesref,commitandblueprint. No - Behind? —
git ls-remote --tags --sort=-v:refname <git_url>and take the first tag.
### 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
gh auth status. Not authenticated → stop: the body file is the deliverable, and thegh issue list -R <slug> --state open --search "<terms>"with the form's label, for the- Ask — the body file's path and its sections, the duplicates found, the version warning
### 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 ``
… cut here, the rest is in the file
## 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>>What it reads, writes and refuses
The skill's own contract, from SKILL.md, in the original wording.
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.
Source: SKILL.md § Contract, at nerviz e4cae27.
What the guard does with it
report is the skill's class, and the list on the left is its territory. The phase opens when the skill runs on a prompt of its own, and ArchHook judges every write against that list. The text on the right is the hook's own.
write_allow of report-issue
- ✓
docs/lessons-learned/** any path outside this list, when the skill opens the phase itself
A refusal exits with code 2 and the message goes back to the model.
> /report-issue … UserPromptSubmit guard prompt exit 0 # phase opened: report-issue (class report) # write_allow: docs/lessons-learned/**
PreToolUse Write(docs/lessons-learned/lessons-learned-001.md) guard write exit 0
PreToolUse Write(pom.xml) guard write exit 2 ❌ `report-issue` is class `report` — pom.xml is outside its territory. write_allow: docs/lessons-learned/** Put the content in the spec as a code block, or finish the run and invoke the skill that owns this path. If the path is legitimately this skill's, widen skill_classes.report in .claude/schemas/extensions.json — retrying will not help.
Who calls it
It is not a step of a chain. It starts from a prompt of its own, /report-issue, and the guard treats it like any other skill: the phase opens, and the territory of its class applies.