From kanso
Use when the user asks for a code review, audit, pre-PR check, quality sweep, or pattern analysis of a diff, branch, module, or codebase. Also use when the user asks to "check" or "look over" their code for issues.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kanso:kanso-audit [scope: diff|branch|module-path|all] [--fresh][scope: diff|branch|module-path|all] [--fresh]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Code review that reports findings, proposes concrete fixes, and — on approval — either hands cleanup off to `/kanso-refactor` or applies the fix in place. The principles from `kanso-principles` govern both the findings and the fixes.
Code review that reports findings, proposes concrete fixes, and — on approval — either hands cleanup off to /kanso-refactor or applies the fix in place. The principles from kanso-principles govern both the findings and the fixes.
Four phases:
allowed-tools deliberately exclude Edit/Write so the investigation cannot modify files.refactor (behaviour-preserving) or behaviour-change (correctness, security, architecture). Show the list in the approval block and wait.refactor-shaped fixes → hand off to /kanso-refactor audit-report. That skill already enforces the behaviour-preserving rule, has the refactor taxonomy, and knows how to split work into commit-able groups. Don't reimplement it here.behaviour-change fixes → apply in place in the main session, one at a time, re-reading each file immediately before editing. These are not refactors; each is a real behaviour change and the user has approved it as such.This skill runs in the calling chat. Never dispatch the audit via the Agent or Task tool, never delegate it to a subagent, never hand it off to a parallel runner. The findings, the approval gate, and any follow-up /kanso-refactor invocation all happen in the user's current transcript so the user can see and act on them directly. A subagent run produces output in a side window the user can't easily reach — that defeats the point.
Same rule for the follow-up: when /kanso-refactor is invoked from the approval gate, it runs inline too.
--fresh for Phase A onlyThe user can pass --fresh to push the investigation into a read-only subagent. Use this when the audit needs an unbiased pass over code the current session has already touched — fresh context cuts the anchoring on decisions earlier in the transcript.
Under --fresh:
Don't dispatch Phase A under --fresh and then quietly run Phases B–D in the subagent too. The fresh-context advantage is for review only; application and verification need to be where the user can see them.
$ARGUMENTS is one of:
diff → the unstaged + staged working tree (default if empty)branch → commits on the current branch vs its upstream or mainsrc/billing/ → everything under that pathall → the whole repo (warn the user this will be noisy on anything larger than a small service)If $ARGUMENTS is empty, default to diff. If the diff is empty, fall back to the last commit and tell the user.
--fresh is a modifier, not a scope. It can appear alongside any scope (e.g. branch --fresh) and triggers the Phase A subagent dispatch described above.
Gather context before reviewing:
!git diff HEAD or !git diff main...HEAD depending on scope!git diff --name-only!git log -n 20 --onelineAGENTS.md, CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, linter configsRead enough of the surrounding codebase to calibrate repo conventions. A finding that contradicts existing repo style is noise, not signal.
Findings sort into four categories (Google's pillars) and three tiers (signal priority).
Correctness — Will this cause incorrect behaviour? Logic errors, off-by-ones, race conditions, missing error handling, security holes, auth bypasses, injection vectors, concurrency problems. Also: the anti-dilution pattern defensive programming theatre, which looks safe but hides failures.
Clarity — Can another developer read this quickly? Over-long functions, dense nesting, single-character or zero-entropy names, comments explaining what instead of why, over-engineering for imagined future needs.
Consistency — Does it match the surrounding codebase? Naming (mixed get/fetch/load), error handling style, decomposition patterns, API conventions, data-type choices. Anything a linter could catch is not a human review finding — note the missing linter rule instead.
Architecture — Does this code belong here? Does it introduce new coupling? Does it break backward compatibility? Does this add a dependency that deserves scrutiny? Does it anticipate a problem that doesn't exist yet? The senior progression: "does it work" → "is it good" → "will it survive".
Tier 1 — Blocker. Would cause production failures or material harm if merged. Logic bugs, breaking API changes, security holes, race conditions, data loss risks.
Tier 2 — Important. Would cause maintainability or scale issues. Architectural violations, missing tests for critical paths, performance regressions, increased coupling, anti-dilution patterns that will metastasise.
Tier 3 — Polish. Subjective or stylistic. Minor naming suggestions, small clarity improvements, nits.
If Tier 1 + Tier 2 findings are fewer than 60% of total findings, the audit is generating noise. Cut Tier 3 findings aggressively until the ratio is above 60%, or omit the Tier 3 section entirely on a clean diff.
Google's rule: think like an adversary, but be polite about it. Explicitly try to construct inputs that break the code:
Surface the adversarial cases that aren't handled. Don't invent ones that don't matter.
From kanso-principles. Call these out by name so they're searchable:
// Step 1:, // Now do Xresult = expr; return resultuserDataProcessingResult, helperFunctionEmit a single tight markdown document. No preamble, no "Let me know if you'd like me to…", no apology. Two-line summary, one-line findings, then the approval gate.
If there are no Tier 1 or Tier 2 findings, emit only the no-change message (see below) and stop.
# Audit: <short scope description>
**Files:** <n> · **Findings:** <t1> blocker, <t2> important, <t3> polish
<Two lines max. Lead with the highest-severity issue in plain language. State whether refactor alone covers it, or whether behaviour changes are also on the table.>
## Findings
[1] `path/to/file.ts:142` — <one-line description> (blocker, refactor)
[2] `path/to/file.ts:88` — <one-line description> (important, behaviour-change)
[3] `path/to/other.ts:14` — <one-line description> (important, refactor)
One line per Tier 1 and Tier 2 finding. Format: [N] \path:line` — <what's wrong> (, ). Use the anti-dilution pattern name in the description when one applies (defensive theatre swallows db errors, not error handling issue`).
Tier 3 findings appear only when the user ran all scope or explicitly asked, and only as additional one-liners under a ## Polish heading. If a finding has no safe mechanical fix (e.g. an architecture disagreement), include it in the list with (no auto-fix) and exclude it from the approval gate's apply count.
Omit "What's good" and "Proposed fixes" detail blocks. The one-liner is the proposal; the diff is the detail. If the user wants more context on a specific finding, they'll ask.
After the ## Findings list, add a plain-language block for each behaviour-change finding so the user knows what would actually shift:
## Behaviour changes — your call
[2] `path/to/file.ts:88`: right now this swallows database errors and returns null. Removing the try/catch means callers see the actual exception — almost certainly what you want, but it's a real behaviour shift, not a cleanup.
One short paragraph per behaviour-change finding. Numbered to match the findings list. Plain language, no jargon. Skip this section entirely if all findings are refactor-shaped.
# Audit: <short scope description>
**Files:** <n> · **Findings:** none
No changes needed. <One short sentence noting what was checked.>
No approval gate. No further prompting. End of turn.
refactor — the fix produces identical behaviour for every input the code already handles. Examples: delete dead code, inline a filler variable, remove a tautological comment, collapse a one-implementation factory, rename a local variable. These are the targets listed in kanso-refactor.behaviour-change — the fix alters what the code does under some input. Examples: fix an off-by-one, remove defensive theatre that was swallowing errors, patch an auth bypass, change an architectural boundary. When in doubt, tag as behaviour-change — that forces an explicit ask rather than a silent refactor.If there is at least one Tier 1 or Tier 2 finding, always end the report with the approval gate. No exceptions — the gate is what makes /kanso-audit a single-command workflow rather than a report-and-wait. Emit exactly this block and stop:
Apply fixes? (<r> refactor, <b> behaviour-change)
y — run /kanso-refactor on the refactor findings
y + behaviour — run /kanso-refactor, then apply behaviour changes inline
behaviour-only — apply behaviour changes inline; skip refactor
pick 1,3 — apply only those (routed by shape)
edit — amend the proposal
n — stop, leave the report in the transcript
Adapt the option list to what's actually present:
y, pick, edit, n. y runs /kanso-refactor.y (apply inline), pick, edit, n. Drop the refactor option.Treat any affirmative phrasing that mentions behaviour ("y and apply the behaviour changes too", "yes do both", "all of it") as y + behaviour. Treat a bare y / "yes" / "go" as refactor-only when both shapes are present — do not silently apply behaviour changes on an ambiguous yes.
Routing rules on apply:
refactor-shaped fix → invoke /kanso-refactor audit-report inline in this chat. Do not edit refactor targets directly from this skill. Do not dispatch the refactor via Agent/Task.behaviour-change fix → apply in the current chat, one at a time. Re-read the file immediately before editing.kanso-refactor's hard rule — refactors and behaviour changes travel in separate commits — applies here too.For any behaviour-change fix in the Correctness category — logic bugs, off-by-ones, security holes, race conditions, missing error handling — write a failing test before applying the fix when the repo has a test suite. The sequence is: reproduce the bug as a failing test, run it to confirm it fails for the expected reason, then apply the fix and re-run.
Skip the test-first step only when:
If you're skipping, say so in the apply step's output. Don't quietly drop the test.
This rule applies to Correctness only. Architecture and Clarity fixes don't require new tests — though running existing ones in Phase D still does.
After any fix lands, run the project's verification command and report the result. Never claim success without evidence.
In priority order:
AGENTS.md / CLAUDE.md — explicit build/test/lint/typecheck commands. Use these first; they're the user's canonical source.package.json scripts — test, typecheck, lint, check, verify.pyproject.toml, tox.ini, Makefile — pytest, make test, make check, ruff, mypy.go.mod — go test ./..., go vet ./....Cargo.toml — cargo test, cargo check, cargo clippy..github/workflows/*, .gitlab-ci.yml, .circleci/config.yml. If CI runs a verification job, run the same commands locally.Pick the narrowest command that covers the touched files. A full test suite is overkill for a one-line refactor; typecheck plus the relevant test file is usually enough. For a correctness fix with a fresh failing test, run that test specifically and then a broader pass.
The verification command may prompt the user for permission on first run — that's expected. Don't reroute around it.
Paste the exit code and the relevant tail of output. Don't paraphrase. On pass:
✓ Verified — <command>
exit 0
<last meaningful lines, e.g. "23 passed in 1.4s">
On fail:
✗ Verification failed — <command>
exit <n>
<failing output>
A failed verification means the fix isn't done. Roll back the edit, iterate, or escalate to the user — but don't move on. Don't hand the user a broken tree and call it complete.
If the discovery turns up nothing, say so plainly:
⚠ No verification command found.
Checked: AGENTS.md, package.json, pyproject.toml, Makefile, CI config.
The fix is applied but unverified — review the diff manually before committing.
Never silently skip. Either verify, or say you didn't and why.
--fresh, which dispatches the investigation only.pick select./kanso-refactor. That's duplication, and it bypasses the behaviour-preserving discipline that skill enforces.behaviour-change.npx claudepluginhub blakecyze/kanso --plugin kansoProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.