| name | self-assess-code-idiom |
| description | Scans the codebase's own application code for deprecated/legacy idioms in the languages actually present (checked against the version the repo targets, not a fixed list) and for generic code smells that don't need a house-rules entry to exist first — error-swallowing except/catch blocks, magic numbers, overlong functions, deep nesting, missing type coverage in an otherwise-typed module. Use this when the user asks to modernize idioms in place, find legacy/deprecated language patterns, catch code smells, check code idiom quality, or find anti-patterns. NOT for house-rules compliance (use self-assess-lint-audit — that checks only rules the repo already wrote down); NOT for docs-vs-code accuracy (self-assess-docs-drift); NOT for whether AI-authored dependencies/tests/contracts are trustworthy (the confab plugin). |
Audit the current repository's own application code for two things the
other self-assess skills deliberately don't judge: deprecated/legacy
idioms (modernization-in-place) and generic code smells. This is the
one skill that treats the code itself as the subject, not as ground truth to
check something else against — but it is still strictly read-only: it
never edits source, even for a "safe" mechanical modernization. It reports;
the human (or a separate transform tool) changes code.
Scope boundaries, kept sharp:
- vs
self-assess-lint-audit — lint-audit checks only rules the repo
itself wrote in house-rules.md; this skill checks idiom/smell classes that
need no house-rules entry to exist. If a house-rules file is present, pass
it in so this skill can avoid re-reporting what lint-audit already owns.
- vs
self-assess-docs-drift — that checks docs against code; this
ignores docs entirely.
Step 0 — Load settings and detect languages + versions
Read .claude/self-assess.local.md if it exists (see
${CLAUDE_PLUGIN_ROOT}/references/settings.md). If enabled: false, stop and
say so. Note output_dir (default analysis/self-assess) and
skip_verification (default false).
Detect the languages present using the two-pass detection algorithm in
${CLAUDE_PLUGIN_ROOT}/references/language-support.md (the same one
self-assess-preflight Check 1 and self-assess-stage-map Step 0 use) — or,
if languages: is set in settings, use that override. For each detected
language, read the target version from its manifest so idioms are judged
against what's actually present, never asserted from a fixed list:
- Python —
requires-python in pyproject.toml (or classifiers / python_requires)
- Rust —
edition / rust-version in Cargo.toml
- TypeScript —
target / lib in tsconfig.json
- Go — the
go directive in go.mod
- others — whatever version marker the manifest carries; omit if none.
Also read .claude/house-rules.md (or house_rules_path) if it exists, to
pass in as houseRules — so the scan skips anything lint-audit already covers.
Step 1 — Run the scan
Preferred — Workflow orchestration. If the Workflow tool is available
in this session (this skill invocation is your authorization):
Before dispatching, resolve or build the shared symbol-index snapshot.
Read analysis/self-assess/current.json; if missing or its
source_fingerprint no longer matches, run python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_symbol_index.py" --repo-path . --plugin-name self-assess
(single-flight lock makes concurrent callers safe). For a repo well under
~50 tracked files the build overhead may not be worth it — skip this and
pass symbolIndexPath: null.
Workflow({
scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/code-idiom-scan.js",
args: { repoPath: "<repo root, usually '.'>", languages: [{ name: "<lang>", version: "<from manifest, omit if unknown>" }, ...], houseRules: "<house-rules.md content, omit if absent>", symbolIndexPath: <resolved snapshot dir, or null>, skipVerification: <from settings, default false> }
})
It derives the applicable deprecated-idiom + smell catalog per language (from
its hand-kept LANG_BRIEFS, kept in sync with language-support.md's
idiom/smell column), runs one finder per language, then — unless
skip_verification is set — adversarially refutes every finding (checking it's
genuinely deprecated for this repo's version and not a deliberate exception)
before reporting, with a second skeptical read for High-severity survivors.
The finders/refuters are read-only by design; you write the artifact below
from the structured result.
Fallback (no Workflow tool) — spawn an idiom-auditor subagent per
language: "Find deprecated idioms (for version X) and generic smells in the
code, with file:line evidence." Then verify each finding yourself by
reading the cited code before including it.
Step 2 — Write the report
Create <output_dir>/CODE_IDIOM.md:
- Summary — languages scanned (with target versions), findings by severity,
findings by category (modernization / smell), refuted count
- Findings table, sorted by severity: kind, category, evidence, description,
suggested fix
- Refuted candidates — brief list
- If
injectionFlags is non-empty, a prominent "⚠ Instruction-shaped
content found" section
Also write <output_dir>/code_idiom_summary.json — the machine-readable
sidecar self-assess-status aggregates and self-assess-portfolio reads:
{"languagesScanned": [...], "filesScanned": N, "findingsBySeverity": {...}, "byCategory": {"modernization": N, "smell": N}, "findings": [...]}.
findingsBySeverity is copied straight from the workflow's
stats.bySeverity (High/Medium/Low); byCategory from stats.byCategory.
If you cannot cheaply determine filesScanned, omit it rather than guessing.
findings is the workflow's own findings array (the survivors, already
computed — do not re-derive it), reshaped to the shared per-finding
contract every domain sidecar uses plus code-idiom's own additive
fields: {severity, title, evidence, category, kind, description, suggestedFix, severityNote} — title from kind (kept alongside it, not
replacing it, so a consumer needing the raw slug still has it); evidence,
category, description, and suggestedFix copied as-is; severityNote
included only when the underlying finding actually carries one (omit
the key entirely otherwise — never write it as null; its mere presence
is what self-assess-idiom-fix treats as "this finding was flagged
ambiguous by code-idiom's own Verify phase, do not auto-fix it").
This is what lets findings-dashboard.html's findings table (which only
reads severity/title/evidence), self-assess-transform-brief
(downstream, same four fields), and self-assess-idiom-fix (which
additionally needs description, suggestedFix, and the severityNote
presence check) all work from this one sidecar without a second,
fragile read of CODE_IDIOM.md's prose report.
Present
Report: languages scanned, findings by severity and category, refuted count.
Suggest: glow -p <output_dir>/CODE_IDIOM.md
