Repository navigation
fix(finding-triage,done-check,implement,codex-plan-review,codex-contract-test-review,quality-list): key defer on the user's direction - #256
Merged
Conversation
…ty-list): key defer on the user's direction defer was entered on two properties nobody enacts: the fix being out of scope for the task, and its being local. A declined non-local fix the user wants tracked reached no entry, an in-scope decline carried past the run reached none either, and an out-of-scope local fix nobody had decided about answered both actionable and defer. defer now takes any direction from the user not to fix in this run that is not a wontfix direction, whatever the fix's locality or scope. With no such direction a finding holds actionable or opens-a-question by locality alone. wontfix states the two things the user must direct, so the boundary between the two entries reads one way. The copies of the old condition go with it: the defer glosses in the two Codex review skills, the locality clause in escape-hatch-necessity, and the per-entry bars under pre-existing instances.
…ings the new defer entry opened Define when a fix is understood, state the wontfix direction as one that keeps no record for a later fix, and move the sentence about task scope into the opens-a-question entry it constrains. escape-hatch-necessity now points at the catalogue for classification and no longer restates how done-check closes a deferral. implement no longer names scope as what puts a concern on the deferral path, and done-check's false-positive example no longer reads as a deferral the user approved.
…user A run that judges a finding out of scope asks the user whether to fix it in this run before fixing it. The section contrasting opens-a-question with uncertain-validity states validity only, and done-check's false-positive example names a constraint that rules the input out.
…entry conditions opens-a-question is entered on investigation or a design choice, so a fix is understood exactly when it is a local edit. A run that judges an edit out of scope asks the user before making it, stated in the actionable entry that governs such a finding. A follow-up is defined once, as what carries a finding to a later fix, and wontfix is the direction to keep none. escape-hatch-necessity ends at calling a recorded deferral a concern.
There was a problem hiding this comment.
🟢 Approval recommended
The revised definitions consistently resolve the reported disposition gaps without leaving stale scope-based classifications.
0 open findings
What changed in this PR
Reworks finding triage so deferral depends on explicit user direction rather than task scope.
Changes:
- Makes
actionable,defer, andwontfixmutually distinguishable. - Updates dependent review and audit guidance.
- Bumps the plugin version to
2026.10.11.
| File | Description |
|---|---|
skills/finding-triage/SKILL.md |
Redefines disposition entry conditions. |
skills/done-check/SKILL.md |
Corrects the false-positive example. |
skills/implement/SKILL.md |
Generalizes the deferral-path wording. |
skills/codex-plan-review/SKILL.md |
Removes the obsolete scope-based defer gloss. |
skills/codex-contract-test-review/SKILL.md |
Removes the obsolete scope-based defer gloss. |
skills/quality-list/items/escape-hatch-necessity.md |
Keeps recorded scope deferrals classified as concerns. |
.claude-plugin/marketplace.json |
Advances the plugin version. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
skills/finding-triage/SKILL.md, the catalogue of dispositions a review finding receives, says each finding receives exactly one. For a valid finding whose fix is understood,actionable,deferandwontfixdid not divide the cases. An out-of-scope fix nobody had decided about met bothactionableanddefer. A fix the user declined and wanted carried forward met neitherdefernorwontfixwhen it was in scope, and neither when it was more than a small edit.deferwas entered on two properties nobody enacts: the fix being out of scope for the task, and its being local. It is now entered on the user's direction, aswontfixalready was, and scope is no longer an entry condition of any disposition.Closes #174 Closes #175 Closes #179
Changes
finding-triage:deferholds a valid finding with an understood fix that the user directs not be fixed in this run, by any direction that is not awontfixdirection.wontfixis the direction to leave it unfixed and keep no follow-up. Entering either takes the finding out ofactionable.finding-triage: a fix is understood exactly when it is the local editactionablenames.opens-a-questionis entered when the resolution needs investigation or a design choice; a scope judgment is not one of its grounds.finding-triage: a run that judges anactionableedit out of scope for its task asks the user whether to make it in this run, and makes it only on a yes. The statement under response selection that the selected edit is applied in the current run is subject to that question.finding-triage: a follow-up is an issue or a note that carries a finding to a later fix.deferkeeps one andwontfixkeeps none.finding-triage: the bar a pre-existing instance of a flaw does not meet is, fordeferandwontfix, the user's direction each entry names. The section contrastingopens-a-questionwithuncertain-validitystates what is known of validity in each.codex-plan-review,codex-contract-test-review: the lists of recurring triage cases carry nodefergloss. Both steps classify under the catalogue by reference.quality-list'sescape-hatch-necessity: a recorded scope deferral is a concern, never N/A. The item says nothing further about how that concern is classified or closed.implement: the done-check step names the deferral path without tying it to scope.done-check: the example of a false positive in the triage step is an input ruled out by a constraint established in conversation..claude-plugin/marketplace.json:metadata.versionis2026.10.11.Impact
No disposition slug is added, removed or renamed, so the value set
review-telemetryrecords, and the queries it documents, are unaffected.One behavior changes for every skill that triages under the catalogue. A valid finding with an understood fix that a run judges out of scope is
actionable, and the run asks the user before fixing it; it becomesdeferorwontfixwhen the user says not to fix it. Before, the run could classify such a findingdeferby its own judgment.done-check's closing step is not edited.Verification
pre-commitran as the commit hook on each of the branch's four commits and reportedmdformatasPassedeach time.A reader with no other context was given the committed
skills/finding-triage/SKILL.mdalone and eleven cases, and asked which entries the literal text admits for each. Every case came back holding one entry:deferdeferdeferwontfixwontfixactionable, with asking the user named as the next stepactionable, with asking the user named as the next stepactionable, applied in the runopens-a-questiondeferdeferFor the declined cases the reader noted that the finding still meets
actionable's own wording, and named the sentence indeferthat takes it out ofactionable.Notes
opens-a-question. This predates the change and is finding-triage: nothing closes a permanently unresolved finding #173's subject.done-check's closing step still closes a concern as resolved, as waived by the user with reasoning, or as a deferral recorded in a follow-up issue filed with the user's approval. It namesdeferand does not namewontfix. How that step relates to the catalogue is also finding-triage: nothing closes a permanently unresolved finding #173's subject.actionableentry now puts to the user fires on the run's own judgment. No input carries the scope a review's findings are judged against #205 asks where a statement of scope should enter a review.