playbook/skills/style-cleanup/SKILL.md

name, description

name	description
style-cleanup	Use when the user asks to format code, fix lint issues, or align style with the repository's existing toolchain without changing behavior.

Style Cleanup

Overview

Use the repository's own formatter and lint contracts without changing behavior. Keep the requested scope, preserve Git state, and prove the resulting diff is style-only.

Use Boundary

Use for requested formatting, lint cleanup, or a final style pass. Do not use for semantic refactors, new tool configuration, or full-repo reformatting without explicit scope.

Workflow

1. Fix the scope and preserve Git state

   Record git status --short. Resolve targets, then inspect git diff --cached -- <targets> and git diff -- <targets> separately. Default to changed files. If a staged-only target is partially staged, stop and ask because formatters edit the whole working-tree file. Never stage, unstage, commit, or discard changes unless requested.

2. Resolve authority in this order

   User instructions and agreed scope → nearest project instructions and canonical repo/CI commands → checked-in tool config → vendored Playbook defaults. A higher source wins; report conflicts instead of combining rules.

3. Choose commands from repository evidence

   Use a canonical repo entrypoint as one unit. Otherwise select only configured tools for target languages; there is no universal formatter/linter order. Run a non-mutating check first when available, then scoped configured fixers. If a tool is missing, report and stop—do not install tools or invent config.

4. Apply and control the blast radius

   Record the initial diff summary and run the chosen commands. If files outside scope change, stop and report them; do not widen scope or silently revert.

5. Verify

   Inspect final cached and working-tree diffs and confirm the index is unchanged. Run git diff --check; rerun the formatter/check for idempotence. If a fixer changes tokens, imports, structure, or any non-style hunk, run relevant behavior tests. Without tests, report behavior preservation as unverified.

Playbook as Authority

Use these only when no higher-priority project rule conflicts:

• TSL: docs/tsl/code_style.md, docs/tsl/naming.md, docs/tsl/toolchain.md
• C++: docs/cpp/code_style.md, docs/cpp/naming.md, docs/cpp/toolchain.md
• Python: docs/python/style_guide.md, docs/python/tooling.md, docs/python/configuration.md

Output Contract

Report Scope, Authority, Commands, Git State, Changes, Verification, and Remaining. Include before/after staged state, diff size, idempotence, checks, behavior tests, and anything unverified.

Quick Reference

Situation	Action
Canonical command exists	Use it; do not build a parallel pipeline
Staged-only target is partial	Stop and ask
Tool expands scope	Stop and report; do not silently revert
Non-style hunk appears	Test behavior or report it unverified
Tool is missing	Report and stop

Example: if package.json defines lint:fix, use that canonical entrypoint for the requested JS files; do not add a separate Prettier pass unless project instructions require it.

Common Mistakes

• Running familiar tools instead of the repository-selected entrypoint
• Giving Playbook defaults priority over project instructions or config
• Staging changes, widening scope, or claiming success without final diff review