detector-findings: let a producer name the remediation skill its findings need

[kyle-sexton]

Graduated from the contract slice of #3031, pruned before merge per the topic-docs convention.

The gap

A conforming findings file reaches the review:fanout fix relay, and the relay decides how to remediate. For ai-slop:audit that decision is wrong for 14 of its 15 rules: the relay classifies its rows as cleanup-class and routes them to /simplify, a code-simplification skill that cannot apply prose rewrites and never loads plugins/ai-slop/skills/audit/reference/rewrite-guide.md, which is where that plugin's rewrite discipline actually lives.

The result is structurally true and semantically empty. A relay pass over an ai-slop findings file retires the findings while applying at most rule-utm-params — the one rule that is genuinely auto-applicable. #3031 narrowed the plugin's own claim to say exactly that, which is honest but leaves the underlying gap.

Why it is a convention change, not a plugin fix

The producer knows which skill can remediate its findings; the contract gives it nowhere to say so. Every adopter has the same shape available to it, so the fix belongs in docs/conventions/detector-findings/ rather than in any one plugin:

• mutation-testing:audit — remediation is a covering test, already declared off-site via Action.
• testing:audit — remediation is at Location but encodes oracle judgment.
• ai-slop:audit — remediation is a guarded prose rewrite owned by the producer's own fix action.

Three adopters, three different remediation owners, one relay that assumes it knows.

Sketch, not a decision

Some way for a crosswalk row (or the findings file) to name the remediation skill, with the relay surfacing rather than mis-applying when the named skill is not the one it would have chosen. The existing off-site-remediation disposition (Action names the target, consumer surfaces rather than auto-applies) is the nearest precedent and may already be the answer with a wider reading.

Deliberately unscoped here. It touches a contract with three adopters and a consumer, and #3031 declined to smuggle it into an unrelated branch.

Related

• feat(ai-slop): unslop-inspired catalog additions, plus the corrections and dogfood config that make them true (0.2.0) #3031 narrowed ai-slop's relay claim to what is currently true.
• docs/conventions/detector-findings/README.md — "The severity crosswalk", the Auto-applicable column, and the Adopters table.

[kyle-sexton]

Fresh-context verification — branch claude/detector-findings-remediation-owner

Diffed against origin/main. Six files changed: docs/conventions/detector-findings/README.md, docs/conventions/detector-findings/CHANGELOG.md, plugins/review/skills/fanout/context/fix-pass-mode.md, plugins/review/skills/fanout/evals/evals.json, plugins/review/CHANGELOG.md, plugins/review/.claude-plugin/plugin.json. No producer plugin file was touched (git diff origin/main...HEAD -- plugins/ai-slop/ plugins/testing/ plugins/mutation-testing/ scripts/ is empty).

---

Q1 — Does the change actually close the gap? VERDICT: CLOSED

Walked in the relay's own text, not in any description of it.

Where the row is routed, and on what signal. fix-pass-mode.md Step 2, "Classification rules", the new fourth bullet:

Producer-owned remediation → route to the named surface, whatever the class. … The declaration is per RULE and sits in that contract's crosswalk: the rule's Auto-applicable cell leads with No, remediated by <invocation>. Resolve it through the rule id the row already carries — every conforming row leads its Finding cell with the qualified <plugin>/<skill>/rule-<slug> id, and the crosswalk is the registry that id resolves against by exact match. A row whose Action cell instead leads with Remediate with <invocation> declares the same thing self-describingly and may be routed on that alone; where the two disagree the crosswalk wins.

So the primary signal is the Finding-cell rule id, resolved against the crosswalk. The Action prefix is an explicitly secondary, optional convenience. This is the crux the review brief flagged, and the routing does not depend on it.

Is the signal present on a conforming ai-slop:audit row today, with no producer change? Yes. Two independent confirmations:

1. plugins/ai-slop/skills/audit/scripts/emit-findings.sh:159 composes the row as
   esc("ai-slop/audit/" slug " " fired " -- " excerpt) for the Finding cell.
2. plugins/ai-slop/skills/audit/context/persist-findings.md, "What each cell says": "Finding leads with the qualified rule id and the detector's fired= condition in the run's own values".

I ran the real pipeline against a two-tell fixture (detect.sh then emit-findings.sh, both unmodified on this branch). The emitted rows:

| 1 | IMPORTANT | high | sample.md:5 | ai-slop:audit | ai-slop/audit/rule-chatbot-artifacts chat-turn residue -- I hope this helps, let me know if you need more. | Delete the chat-turn sentence; keep any real content it carried in document register |
| 2 | SUGGESTION | high | sample.md:3 | ai-slop:audit | ai-slop/audit/rule-em-dash zero-tolerance -- Some prose with an em dash — right here. | Guarded rewrite via /ai-slop:audit fix (judgment; see crosswalk row) |

Note row 1: its Action cell contains no invocation at all. If routing depended on an Action prefix, rule-chatbot-artifacts would still be misrouted. It is not, because the crosswalk path is the load-bearing one, and ai-slop/audit/rule-chatbot-artifacts resolves by exact match to a crosswalk row whose Auto-applicable cell reads No, remediated by /ai-slop:audit fix — the sentence usually deletes, but chat residue….

The crosswalk cells are actually written. I extracted column 5 for all 22 crosswalk rows. All 14 non-rule-utm-params ai-slop/audit/* rows lead with No, remediated by `/ai-slop:audit fix` —. ai-slop/audit/rule-utm-params alone keeps Yes — contained to Location, and the strip is meaning-preserving….

Does Step 4 invoke the named skill rather than /simplify? Yes, in a dedicated subsection between the correctness and cleanup routes:

### Producer-owned → the surface the row names … "Group them by <invocation> and invoke each named surface ONCE over its rows, in Rank order — hand it the rows, not a re-derivation of them."

and the cleanup section is fenced from behind:

"Rows Step 2 routed to a producer-owned surface never reach here, whatever their class — that route is what keeps a prose-rewrite finding out of a code-simplification skill."

Step 3's plan template also gained - Producer-owned (<p>) → <invocation>, one line per named surface, and Step 5's report and record gained the matching Producer-owned (<p>) line.

Is the unavailable-skill fallback safe? Yes, and it is the strictest of the three routes:

"Invoke only what is ALREADY available in the session. Never install, fetch, enable, or shell out… Unavailable, unrecognized, or malformed invocation → surface the rows, listing the invocation the producer asked for… NEVER fall back to applying these rows directly, and never hand them to /simplify… This is the one route with no direct-apply fallback, and the asymmetry with /simplify below is deliberate."

One residual, disclosed by the change rather than hidden by it. fix-pass-mode.md Step 2 states "a row whose contract cannot be resolved and whose Action declares nothing simply takes its ordinary class — the behavior before this rule existed", and README says the same under "When the contract cannot be resolved". That means the original bug re-enters verbatim on a session that cannot reach the contract. Two things bound it but neither eliminates it: (a) README's argument that a producer which cannot fetch the contract is required not to write at all, so a findings file's existence is evidence the contract was reachable to the producer, which is not the same session as the consumer; (b) the only URL the relay is given is in Step 2's off-site bullet and points at main (raw.githubusercontent.com/.../main/docs/conventions/detector-findings/README.md), so the new cells are not visible to a live relay until this branch merges. Neither is a defect in the change; the second is just a merge-ordering fact worth stating.

---

Q2 — Is the new field genuinely necessary? VERDICT: JUSTIFIED (no new field or column was added at all)

No column was added anywhere. Verified independently of the prose:

• The crosswalk header is unchanged at five columns: | Rule id | What fires it | The test the disposition is argued from | Tier or disposition | Auto-applicable | (README.md:210).
• scripts/check-detector-findings-crosswalk.sh is untouched on this branch, and still asserts the five-column shape (# A well-formed 5-column row splits into 7 fields: an empty lead, five cells, at line 98). bash scripts/check-detector-findings-crosswalk.sh --check → Crosswalk OK: 22 rule row(s), every disposition argued from a stated test. (exit 0).
• plugins/review/skills/fanout/context/default-mode.md "Findings-file shape" is untouched; the seven-column findings table is unchanged. The testing:audit emitter still prints | Rank | Tier | Confidence | Location | Surface(s) | Finding | Action | (cant-fail-scan.sh:349).

The whole declaration rides a leading token inside an existing cell, which is the same device the rule id already uses inside Finding.

Independently evaluating the change's own load-bearing claim. README, "When the remediation is owned by the producer's own skill":

"Auto-applicable: No has no path to the route that actually misapplies these rows. Step 4's surface-instead-of-auto-applying fence sits under its correctness-class heading."

I verified this by reading Step 4 directly rather than taking the claim. Step 4's structure is:

• ### Correctness-class → sequential scope-fenced fix (line 133), which contains the bullet - **Surface instead of auto-applying** when a fix is low-confidence, needs architectural judgment, has high blast radius, or **its remediation lies outside the finding's Location** (line 139).
• ### Producer-owned → the surface the row names (line 142, new).
• ### Cleanup-class → optional in-session /simplify`` (line 151), which contains no surface-instead-of-applying fence of any kind.

grep -n "Auto-applicable" plugins/review/skills/fanout/context/fix-pass-mode.md returns exactly one hit, the new Step 2 bullet at line 84. So before this change, Auto-applicable was read by the relay nowhere, and a cleanup-class row reached /simplify regardless of its crosswalk value. The claim is sound as written.

The off-site half of the argument is likewise sound. Step 2's off-site trigger has two limbs and both are site limbs ("the Action names a different file, or the producing detector's contract declares the rule off-site"), and its destination is surface-only, which for ai-slop:audit would trade a misapply for a non-apply while the producer ships a surface that can actually do the work. The existing shape did not already express producer ownership.

---

Q3 — Does the change break either other adopter? VERDICT: NO BREAKAGE

mutation-testing:audit and testing:audit cannot be misrouted, because the route fires only on a specific leading token that neither writes.

• Crosswalk cells. mutation-testing/audit/rule-survivor-productive → No — the remediation is the covering test, not Location; rule-survivor-unclassified → No — same off-site remediation; rule-survivor-arid and rule-survivor-equivalent → Not applicable — no row. testing/audit/rule-zero-assertion, rule-recomputed-expectation, rule-mock-only-oracle all lead No — …. None leads No, remediated by.
• Producer surfaces. grep -n "remediated by\|Remediate with" plugins/mutation-testing/skills/audit/context/persist-findings.md plugins/testing/skills/audit/scripts/cant-fail-scan.sh returns zero hits, so neither the Action shortcut nor a self-describing declaration fires either. mutation-testing's Action names the covering test file (persist-findings.md:212, "Action names the covering test file"); testing's Action proposes an assertion (cant-fail-scan.sh:268, "Repair, not pruning — every Action proposes an assertion, never a deletion").
• Existing dispositions preserved. Ordering is explicit in Step 2: "Decide off-site FIRST all the same: a row that is both off-site and owned stays surface-only, because a fence this step cannot enforce is not made enforceable by naming someone else to cross it." mutation-testing's rows are off-site by construction, so they hit the off-site rule before the owner rule is ever consulted. testing's rows are at Location and declare no owner, so Step 2's closing clause applies verbatim: "a row whose contract cannot be resolved and whose Action declares nothing simply takes its ordinary class — the behavior before this rule existed."
• Step 3/Step 5 counts. The new Producer-owned (<p>) line is additive; with p = 0 for both adopters, their plan and record output is byte-identical to before.

---

Q4 — Are all three adopter rows still accurate? VERDICT: ACCURATE, with one precision nit

All three rows were edited (word-diff shows the mutation-testing and testing rows gained exactly one appended sentence each; the ai-slop row gained a larger block).

ai-slop:audit — all checked claims true.

• "twelve SUGGESTION style rules, three IMPORTANT generation-residue rules": emit-findings.sh:112-118 returns IMPORTANT for exactly rule-knowledge-cutoff-disclaimer, rule-llm-citation-artifacts, rule-chatbot-artifacts; 15 crosswalk rows total, so 12 SUGGESTION. ✅
• "only rule-utm-params is auto-applicable, and its other fourteen rows are contained to Location": 15 − 1 = 14, and all 14 carry the new lead. ✅
• "which the relay resolves through the qualified rule id every emitted row already leads its Finding cell with": confirmed against emit-findings.sh:159 and against a live emitted file. ✅
• "The declaration required no change to what this producer emits": confirmed by the empty git diff over plugins/ai-slop/. ✅
• "its emitted Action cells already describe the repair and already name the fix action on the rules with nothing more specific to say": correctly hedged. The default branch of rule_action() returns Guarded rewrite via /ai-slop:audit fix (judgment; see crosswalk row); the five rules with bespoke Action text (rule-knowledge-cutoff-disclaimer, rule-llm-citation-artifacts, rule-chatbot-artifacts, rule-filler-phrases, rule-stacked-hedging) do not name it, and the row's qualifier covers that. ✅
• "After that fix runs the skill re-runs the detector and re-emits": matches persist-findings.md "Re-running". ✅
• /ai-slop:audit fix is a genuinely runnable invocation: plugins/ai-slop/skills/audit/SKILL.md frontmatter argument-hint: "[audit|fix] [target]" and the "Fix flow (explicit invocation only)" section. reference/rewrite-guide.md exists. ✅

testing:audit — added sentence true. "It declares no remediation owner… so its cells keep the plain No — <reason> form and Step 4's judgment fence surfaces the rows, exactly as before." All three cells verified as No — …. ✅

mutation-testing:audit — added sentence, one precision nit. "It declares no remediation owner and is unaffected by that disposition: its Auto-applicable cells keep the plain No — <reason> form, and off-site is decided first in any case."

The load-bearing half (no cell leads No, remediated by; off-site decided first) is true. But "its Auto-applicable cells keep the plain No — <reason> form" is imprecise: only two of its four cells use that form. rule-survivor-arid and rule-survivor-equivalent read Not applicable — no row, which is a different one of the four leading forms the same change enumerates two sections earlier. Suggest "its Auto-applicable cells keep their existing No — <reason> and Not applicable — no row forms". Not a functional defect.

---

Also report

1. Internal contradiction between README and fix-pass-mode.md: none found. Every cross-reference lines up: the off-site-first ordering, the crosswalk-wins tiebreak when Action and crosswalk disagree, the surface-when-unavailable disposition, the never-install / never-direct-apply fence, and the "contract unresolvable → ordinary class" fallback all appear in compatible wording on both sides. README's "ai-slop:audit writes a near form of it today (Guarded rewrite via /ai-slop:audit fix)" is honest about it being a near form rather than the routable Remediate with <invocation> lead, which is what makes the crosswalk path load-bearing rather than decorative.

2. Claims that outran the code: none found. The only files the change asserts new behavior of are README.md and fix-pass-mode.md, both of which it changed. The claim that most invited an overrun ("The declaration required no change to what this producer emits") is the one I verified hardest, and it holds: the rule id was already emitted, and the crosswalk lookup needs nothing else.

3. plugins/ai-slop/skills/audit/SKILL.md now contains claims this change made FALSE. Reporting, not fixing.

Two places, both untouched by this branch:

• SKILL.md:26-30 (detection-layer 1): "What the relay can actually apply is narrow: rule-utm-params alone is auto-applicable, and the relay's cleanup route is a code-simplification skill that never loads this skill's rewrite guide. Every other rule is /ai-slop:audit fix work — the findings file is how a consumer sees them, not how they get rewritten." The /simplify sub-claim remains literally true, but the framing ("What the relay can actually apply is narrow", "the findings file is how a consumer sees them, not how they get rewritten") is now false: after this change the relay routes the other 14 rules to /ai-slop:audit fix, so the findings file is how they get rewritten when that skill is in session.
• SKILL.md:62-66 (audit flow, step 6): "Recommend review:fanout fix only for rule-utm-params findings — it is the one rule the relay can apply meaning-preservingly; routing prose rewrites there retires the findings without fixing them." This is now flatly false and, worse, it is a recommendation the skill gives the user: it tells operators not to use the exact route this change built for them, and its stated reason ("retires the findings without fixing them") is precisely the behavior the change eliminated.

This is a genuine repo-level contradiction: the contract's ai-slop:audit adopter row and the ai-slop:audit skill body now describe opposite relay behavior. It sits in the ai-slop plugin rather than in review, so leaving it out of this diff is defensible scoping, but it should not ship unaddressed — an operator reading SKILL.md will still be steered away from the new route. A follow-up in ai-slop (with its own version bump and changelog entry) looks like the right shape.

4. Two smaller, incidental observations, both pre-existing and neither introduced here.

• Backticks inside the declared lead. The crosswalk cells are written No, remediated by `/ai-slop:audit fix` — …, while the obligation text and the disposition table write it unfenced as No, remediated by <invocation>. The new Enforceability row calls the check "a literal-prefix read of a cell the crosswalk gate already parses" and marks it "Unbuilt; it is one condition away in that gate". Whoever builds that condition needs to strip the backticks; worth one clarifying clause in the obligation so the gate and the cells cannot drift apart.
• ai-slop:audit emits an unparsable date:. emit-findings.sh:108 is DATE_UTC="$(date -u +%Y-%m-%dT%H-%M-%SZ)", producing date: 2026-08-21T05-45-10Z (hyphens where ISO-8601 requires colons). fix-pass-mode.md Step 1 classes that as UNREADABLE, which fails open ("A candidate whose date: is missing, empty, or unreadable fails the test and STAYS in the set"), so it costs at most one extra pass and drops nothing. Entirely out of scope for this change; noting it only because it is on the same producer/consumer seam and would be cheap to fix in the same follow-up as item 3.

Gates run, all green:

Gate	Result
bash scripts/check-detector-findings-crosswalk.sh --check	Crosswalk OK: 22 rule row(s), every disposition argued from a stated test. (exit 0)
bash scripts/check-changelog-parity.sh --check	Every versioned plugin has a CHANGELOG.md …, and none documents a version above its manifest. (exit 0)
bash plugins/skill-quality/scripts/check-evals-quality.sh plugins/review/skills/fanout/evals/evals.json	PASS (0 warning(s) across 1 file(s))

Evals 36 and 37 cover the happy path and the unavailable-surface path respectively, and 36's expectations correctly pin the discriminating behavior ("Resolves each row's qualified rule id against the detector-findings crosswalk … not from the finding's prose", "Routes … NEVER to /simplify, even though their content classifies as cleanup", "Does NOT treat the rows as off-site"). No file was modified and no PR was opened by this verification pass.

---

Generated by Claude Code