| name | self-assess-idiom-fix |
| description | Applies exactly the eligible "modernization"-category findings from self-assess-code-idiom's code_idiom_summary.json -- mechanical, single-location deprecated-idiom rewrites (e.g. Optional[X] to X | None) -- via the idiom-remediator agent, then hands every fix off to andon-verify's adversarial tribunal for proof (never self-verifies, no exception even for trivial rewrites). Use this only when the user explicitly wants to apply code-idiom's modernization findings, not just read them, and has set idiom_fix.mode to "fix" in .claude/self-assess.local.md. This is one of only two skills in self-assess with Edit access to target source (the other is self-assess-transform-execute) -- every other self-assess skill, including self-assess-code-idiom itself, is read-only. Do not use for "smell"-category findings (those are never auto-fixed by this or any self-assess skill), for architectural Merge/Split changes (self-assess-transform-execute), or for house-rules violations (self-assess-lint-audit has no auto-fix path). |
Apply self-assess-code-idiom's eligible modernization findings,
clustered by file and kind (Step 1a) and dispatched to the
idiom-remediator agent once per cluster, via one of only two
Edit-capable paths in self-assess (the other is
self-assess-transform-execute).
self-assess-code-idiom itself remains unconditionally read-only; this
skill is the separate, explicitly-gated place where a subset of its
findings can actually be applied.
This skill never verifies its own output. Its last step, for every
fix, is always a hand-off to an independent process — never a
self-review. This applies with zero exceptions, even to the most
mechanical single-line rewrite, per this plugin's deliberate choice to
prioritize one consistent safety story over proportionality to blast
radius.
Step 0 — Load settings and check authorization
Read .claude/self-assess.local.md (see
${CLAUDE_PLUGIN_ROOT}/references/settings.md). If enabled: false,
stop. If idiom_fix.mode is not fix (default propose), stop here
and say so plainly: "self-assess-code-idiom already reports
modernization findings; applying any of them requires setting
idiom_fix.mode: fix first — this is a deliberate authorization gate,
not a bug." Do not proceed in propose mode under any circumstance,
including a direct request to "just do it anyway" — redirect the user to
the settings file.
Step 1 — Build the eligible-findings list
Read <output_dir>/code_idiom_summary.json. If it doesn't exist, stop
and say self-assess-code-idiom hasn't run yet.
Filter its findings[] array to entries where both hold:
category === "modernization" (never "smell" — permanently out of
scope; fixing a smell requires design judgment a mechanical rewrite
can't supply).- No
severityNote field present (its presence means
self-assess-code-idiom's own Verify phase already flagged this
finding as a split/uncertain verdict — this skill never second-guesses
that by attempting a fix anyway).
This is the eligible-findings list for the run. Zero eligible
findings is a valid, expected outcome, not an error path — a
fully-migrated codebase genuinely has nothing to fix here. Report "0
eligible findings — nothing to do" plainly and stop; never lower the
filter criteria or otherwise manufacture a finding to justify the run.
Step 1a — Cluster by file and kind
Group the eligible-findings list from Step 1 into clusters, keyed by
(file, kind) — file is everything before the last :<digits> in the
finding's evidence string, kind is the finding's own kind field
(the specific deprecated idiom, e.g. optional-union-syntax). Findings
that share both are the same anti-pattern recurring at different lines
in the same file — these become one cluster, dispatched as a single
idiom-remediator call in Step 3. A finding that shares its (file, kind) with nothing else is a singleton cluster of size 1 — the common
case stays exactly as fast as before. Never cluster across files or
across different kind values, even when the fixes look superficially
similar.
For each cluster with more than one member, check whether the symbol-graph
built by build_symbol_index.py (resolve-or-build per
references/parallel-safe-research-protocol.md, same as this plugin's other
Workflow-tool skills) has an index for the cluster's file at
symbol-graph/<file-slug>/_index.json. Each finding's evidence gives a
path:line, never a resolved symbol name — read that one small index file
(sorted by line) and pick the nearest enclosing entry (the last one whose
line is <= the finding's line, or the closest overall if none qualifies),
then read that entry's own symbol-graph/<file-slug>/<slug>.md doc. If its
"Possibly related" section links to a same-file symbol whose location is
not already one of this cluster's cited locations, attach a
possiblyRelated note (the other symbol's name, kind, and line) to the
cluster for Step 3 to pass along. This never changes cluster membership or
blocks the dispatch — a missing, stale, or unbuilt symbol-graph/index is a
normal, expected outcome, not an error; proceed exactly as before when it's
absent.
Step 2 — Dirty-tree gate
Run git status --porcelain. If it's not clean, tell the user
plainly that this step is about to edit tracked files and ask them to
commit or stash first, or explicitly confirm proceeding anyway — do not
proceed silently on a dirty tree (same discipline
self-assess-transform-execute and confab-cycle's fix mode use).
Checked once per invocation, before touching anything.
Step 3 — Dispatch idiom-remediator, once per cluster
Loop over the clusters from Step 1a within this one invocation. For each
cluster, dispatch the idiom-remediator agent
(agentType: 'self-assess:idiom-remediator') exactly once, passing the
entire cluster's array of {evidence, description, suggestedFix}
entries — plus, when Step 1a attached one, a possiblyRelated note asking
idiom-remediator to Read that other location before editing and return
blocked for the affected cited location(s) if the rewrite would actually
touch or depend on it, rather than assuming independence from the string-key
match alone — never a dispatch spanning more than one cluster (i.e. never
more than one file, never more than one kind). The agent returns one
result per location in the cluster ({file, line, status, description, reason?}, ... — see its updated Output contract). For each location that
comes back blocked, report why verbatim; for each applied, carry it
into Step 4. Do not retry a blocked location with a broader prompt or a
second guess at the fix — and a blocked location never blocks the rest
of its cluster from being applied.
Step 4 — Hand off for verification (do not skip, do not self-verify)
Immediately after each cluster idiom-remediator returns — before moving
to the next cluster in the loop — report explicitly, once per applied
location in that cluster:
This change is unverified. Do not treat it as correct. Run
andon-verify (strategy a — the adversarial tribunal: independent
Defender, Challenger, and Verifier agents, never a self-review) against
this fix, or invoke andon-loop if you want this and future fixes
proven and recorded inside its OKF ledger. If andon is not installed,
verify this change by hand before trusting it — this skill does not
implement its own verification, on purpose.
Each fix gets its own hand-off message — N findings fixed this run means
N separate hand-offs, regardless of how many clusters they were
dispatched in, never one summary claiming the batch as a whole is
"done."
Never commit or push, at any point in this skill.
Present
Report: how many eligible findings were found, how many were fixed vs.
blocked, and the verification hand-off message above, once per fix,
verbatim. If Step 0 or Step 2 stopped early, report that instead —
clearly, as the actual outcome of this run, not as an error to apologize
for.
