When a finding is wrong
A rule that fires on correct code is a defect in the rule, not something for your project to work around. So is a rule that stayed silent on code it should have caught, and a rule your assistant had in front of it and did not follow. Each of those is fixed once, in the toolkit, and every project gets the fix once the toolkit change is published.
That is what /improve-toolkit does. It is not for reviewing your own code against the analyzer — that is /review — and a warning is not a wrong finding: a warning is a case the rule cannot settle on its own, and deciding it is yours, as Read a finding explains.
How to report it
From your project, tell your assistant what happened, with the file and the line:
- The analyzer flagged something that is correct: which rule, on which line, and why you think the code is right.
- The analyzer missed something that is wrong: the line, and the rule you expected to report it.
- Your assistant did not follow a rule: which rule, and where it was ignored.
You do not need to type /improve-toolkit; a report like that starts it. The file and the line matter more than the description, because the first thing it does is run the analyzer on that file and look at what actually comes back.
It needs a copy of the toolkit
The fix is written in the toolkit's own repository, so the command has to find a copy of it on your computer. It tries the folder beside your project, then the usual places, and only accepts one that really is the toolkit. It tells you the path it found and waits for your confirmation before writing anything. When it finds several, or none, it asks you for the path rather than guessing.
What it decides first
Is it the formatter? When what you reported is simply what the project's formatter produces, there is nothing to fix: a rule written against the formatter would lose on every file. It writes down the convention and stops.
Otherwise it puts the report in exactly one of five cases, with the evidence for it:
| Case | What happened | What gets fixed |
|---|---|---|
| False negative | The standard already forbids it, a check could prove it from the file, and nothing reported. | The automatic check. |
| False positive | Correct code was flagged. | The check or the rule's wording, whichever is too broad. |
| Standard gap | No rule covers the case at all. | A new rule, with a check when one file is enough to prove it. |
| Judgement rule | The rule exists and is clear, it was not followed, and no machine reading one file can decide it. | Nothing yet — see below. |
| Workflow gap | The rule and its check are right, but nothing ran them. | The command or agent that should have. |
A judgement rule stops the run. It explains why the rule was ignored and offers three options: strengthen the standard's wording, strengthen the command or agent that should have applied it, or leave it as it is. A rule that needs judgement is never fixed with a check that guesses. Those rules are the ones in What the analyzer cannot check.
The plan you approve
Before writing a single file in either repository, it shows you the case and the evidence, the exact rule text to add or change and where it goes, the check or the command to change, and which edge cases the fix covers and which it leaves out on purpose. Nothing is written until you confirm.
Fixed against the file that failed
The fix is proved on your file, not on an example. After changing the rule or its check in the toolkit, it reloads the rules and runs the analyzer on the file that failed, again and again, until it reports exactly the right problem on the right line and nothing about the code that is valid.
A fix to a command or an agent is proved by reading the changed instruction against your report instead.
Then your project is swept
The same pattern is almost certainly somewhere else in your project. Once the rule is right, it runs that one rule over your whole project, reads every hit, and groups them by pattern. A hit on correct code means the check is still too broad, and it goes back to fix the check rather than judging file by file.
You get the whole list — how many files, the pattern of each group, and a concrete question for every doubtful one. No file in your project is changed before you approve it. Then only what you approved is corrected, and each corrected file is run through the analyzer again.
How it closes
In the toolkit, a changed check gets a test with the case that failed and the case that must keep passing, and the test is run. A changed command, agent, guide or standard is reviewed by workflow-reviewer, and a changed standard, command or agent has its Spanish copy generated again rather than edited by hand. It makes one commit in the toolkit, and commits in your project grouped by area. Nothing is pushed: publishing the toolkit change is yours.
Next
- Read a finding — what a finding is made of, and errors against warnings.
- Write a new rule — how a rule is written when a case has no rule at all.
- The analysis history — the run that failed and the one after the fix, side by side.