Kevin Veen-BirkenbachandClaude Opus 5.5
8b0c287ada
The skill listing stood at 1498 of 1500 words; the trimmed descriptions bring it to 1420, so the new kvb-check-ansible description fits without pushing others out. 🎯 Fix: 95 % 💥 Break: 1 % 💸 Cost: 99 % ⏱️ Time: 100 % 🛡️ Security: 100 % 🏆 Score: 95 🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.7 KiB
name, description
| name | description |
|---|---|
| kvb-code-refactor | Refactor every uncommitted file to the project's standards without changing behaviour. Trigger when asked to clean up, tidy or polish them. |
The unit of work is the uncommitted change set, not the repository. Behaviour stays identical: a refactor that changes what the code does is a bug.
Step 1: fix the file set
Read it from git status --porcelain, never from memory: modified, added,
renamed and untracked files, without deleted files, binaries, lockfiles,
vendored trees and generated output. Restate the list in one line before
touching anything; if it is empty, say so and stop.
Never git stash or revert a working-tree file to compare: others share this
tree. Read the committed version with git show HEAD:<path> into a temporary
file.
Step 2: get a safety net first
Behaviour stays provable only through a check before and after: tests that
cover the change set run now and give the green baseline; a suite already red
is reported, not refactored around. No coverage: read net.md next to this
file before editing.
Light runs (targeted tests, ruff, single lint files) start once watch.py admit --kind test-nostack of the kvb-org-organize skill prints grant; no
chair request.
Step 3: refactor each file
Read the whole file first; the project's own standards (formatter config,
linter rules, existing idioms) outrank generic preference. Find callers,
duplicates and existing helpers through the codebase-memory-mcp graph first
(search_graph, trace_path, get_architecture; the kvb-agent-optimize
skill sets it up), grep and read after.
- SRP: one file, one responsibility; one function, one reason to change. A unit that needs an "and" to describe it is two.
- SPOT: every fact (constant, path, schema, rule) lives in one place; everything else references it.
- KISS: the simplest construct that works; no abstraction without a second caller today, no configuration for a value that never varies.
- DRY: logic is written once; a literal repeated three times is a missing constant.
- File size: read
size.mdnext to this file for a file over 250 lines. - Duplication: fold repeated logic into the existing helper; a new one only when two or more call sites need it now.
- Dead weight: unused imports, variables and parameters, unreachable branches, single-value flags, one-implementation abstractions.
- Naming: names state what a thing is, in the file's convention.
- Shape: split a function that needs a scroll; return early instead of nesting; magic values become a named constant at the use site.
- Errors: never widen or swallow a caught exception, never remove a validation or security check to shorten code.
- Comments, defaults: the
kvb-code-cleanskill.
Never reformat a region without a substantive fix: cosmetic churn buries the real change. An architectural problem the change set cannot fix is reported, not half-done.
Step 4: keep behaviour provable
- Re-run the step 2 net; require the baseline's green result.
- Never fold a bug fix, feature or dependency change into a refactor; name a found bug in the report for a separate change.
- Run the project's cheap checks for the touched files (formatter, linter, the module's unit tests). Never start a full suite, build or deploy on your own: propose it for the operator to trigger.
- Report what was verified and what was not, an unverified refactor as unverified.
Step 5: report
One line per file: what changed and why it is safe. Then one line on what was deliberately left alone (architectural findings, bugs, skipped files) and the exact command the operator can run to validate. Commit only when the operator asked.