Code Hygiene
Passing tests, typecheckers, and formatters (ruff, eslint, prettier, rustfmt, gofmt, clang-format) verifies execution and surface syntax rather than 2D structural readability. Run codehygiene on newly written or modified code to catch structural clutter while applying engineering judgment to every diagnostic.
Preview Status & Scope Disclaimer
- Early preview & benchmark collection:
codehygieneis an evolving preview; circuit thresholds continue to be calibrated, and edge cases can occur. Real-world review and issue reports directly guide circuit improvements. - Zero-vocabulary byte-grid geometry: No tokenizer, AST parser, or English word table is used. Identifier spelling (
*_old,*Manager, math symbols) and domain exception semantics are intentionally ignored; only indentation contour, horizontal expression density, vertical stanza pacing, punctuation skeletons, and cross-line bit similarity are measured. - Step 1 toward harness hooks (not a long-term skill): Deterministic execution inside an agent harness (
PostToolUse,Stop, or lint hooks) is the long-term target. Shipping this skill collects real-world feedback and benchmark cases toward zero-token harness hooks. - Scope to touched diffs: Running skill-driven refactor loops across large repositories or legacy modules wastes tokens. Keep checks scoped to small touched diffs, and warn the user before attempting broad sweeps (offer a read-only
--jsoncheck on 1–2 target files instead).
Run It
The pure-NumPy runtime (__init__.py, __main__.py, grid_target.py) and weights.npz (8.20 KiB zero-vocabulary 1.58-bit ternary model) are bundled inside <SKILL_DIR> (the directory containing this SKILL.md) and run offline across macOS, Linux, and Windows:
python3 "<SKILL_DIR>" <touched-files> --check --no-color- Active virtualenv, conda, or Windows
python:python "<SKILL_DIR>" <touched-files> --check --no-color - Environments without
numpypreinstalled:uv run --with numpy "<SKILL_DIR>/__init__.py" <touched-files> --check --no-color - Installed on
PATH:codehygiene <touched-files> --check --no-color - Structured JSON output (
{"score": ..., "squiggles": [...]}, plustarget_scoreandtarget_gridwhen a cleaner grid is found): pass--json
Under --check, clean files print nothing and exit 0. A flagged file prints its score, the flagged lines (N!|), and a target: silhouette that the model has verified scores cleaner:
sync.go 0.233/1 -> 0.881/1
9!| if sink.Send(item.ID, item.Payload) {
10!| sent += 1
target:
3 | ■■,■■■:=■■■■■■■{
4 | ■■■:■■■ <-4..8
5 | ■■■:■■■■ <-4..8
6 |
7 | ■■■■■■(■■■,■■■■■■){ <-9
8 | ■■■=■ <-10
9 | }0.233/1 -> 0.881/1: current score, then the score of the target grid.- Silhouette rows:
■stands for two bytes of code; brackets and;:,=are kept; indentation is drawn at half width.<-Nor<-a..bnames the source lines a target row came from. Rows without<-are unchanged context. - Read the target as a shape to aim for (here: lines 4–8 collapse into two guard rows and the send loop moves up two levels), not as code to paste. Squiggle
kindnames appear only in--json.
Supported extensions (20+ languages): .py, .pyi, .ts, .tsx, .js, .jsx, .mjs, .cjs, .rs, .go, .c, .h, .cc, .cpp, .cxx, .hpp, .zig, .java, .cs, .rb, .swift, .kt, .kts, .scala, .sql, .pl, .pm, .vb, .f90, .f95, .f03, .f08, .m, .lua, .php, .sh.
Workflow
- Verify behavior first: Pass syntax checks, typecheckers, and unit tests before running
codehygiene. - Scope to small touched diffs: Pass only newly created or substantially edited files from the current turn. On existing files, pass
--jsonand inspect only line ranges modified in the current turn. - Apply high-value fixes (at most 2 passes): Fix genuine geometric squiggles (
>= 0.55) in touched code, using thetarget:silhouette as the shape to aim for, then re-runcodehygieneand tests once. Cap cleanup at 2 passes. - Skip unhelpful or conflicting edits: Leave code untouched when resolving a squiggle would alter runtime behavior, clash with an enforced project linter rule, fight normal language idioms, or fragment concise readable lines into awkward pieces just to force exit code
0. - Ask for review & issue feedback:
- Summarize
codehygiene-motivated refactors in one short note for user review. - Whenever an edit is skipped or disliked by the user, keep or restore the preferred code immediately, note that
codehygieneis an early preview collecting real-world cases, and ask whether an issue should be opened onbrianbell-x/codehygiene.
- Summarize
Opening Feedback Issues
Once confirmed by the user:
- Construct a minimal synthetic reproducer snippet (omit proprietary logic, credentials, and internal identifiers).
- Include the language/extension,
codehygiene -Vversion, squigglekind+ probability, any conflicting linter rule, and a one-sentence explanation of why the diagnostic or suggested refactor was unhelpful. - Run
gh issue create --repo brianbell-x/codehygieneand share the URL, or provide a pre-filledhttps://github.com/brianbell-x/codehygiene/issues/newlink whenghis unavailable.
Squiggle Reference (6 Geometric Kinds)
Squiggle kind |
Geometric Trigger | Recommended Fix (When Genuine) |
|---|---|---|
deep_nesting |
Pyramid control flow (4+ compound indent steps inside a function/method) |
Invert conditions into early return / continue guard clauses or extract a flat helper. |
dense_line |
Chained .a().b().c() call trains, nested ? : ternaries, ;-packed statements, or wide unwrapped lines (>96–110 code cols) |
Split packed chains or ternaries into clear intermediate bindings without awkward micro-wrapping. |
cramped_layout |
Unbroken 20+ line imperative statement walls with zero blank-line separation, or ragged off-grid indentation |
Separate setup, transformation, and return phases with single blank lines and align block indentation. |
duplicate_block |
Copy-pasted or alpha-renamed 4+ line imperative stanzas 4–31 lines apart |
Extract shared logic into a parameterized helper or data-driven loop. |
repetitive_structure |
4+ parallel if x == lit equality-comparison branches |
Replace repetitive branch ladders with a lookup map, dictionary, or dispatch table. |
comment_echo |
Standalone comment echoing next-line tokens, // ... / # ... elisions, or 2+ lines of commented-out code |
Delete echoed comments, placeholder elisions, and dead commented-out code; keep concise why or invariant notes. |
Guardrails
- Execute the CLI directly rather than guessing scores from visual inspection.
- Do not game scores by cramming statements, inserting artificial blank lines every 2 lines, adding trivial padding helpers, or raising
-t/--thresholdabove0.55; skip false positives openly instead. - When
stderrprints acodehygieneupdate notice, mention the available update briefly at the end of the turn (npx skills update codehygiene -yornpx skills update codehygiene -g -y).