playbook/skills/style-cleanup/SKILL.md

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 Workflow（整理代码风格 / 格式化）

Overview

Apply the repository's existing formatter and lint toolchain without changing behavior. Core principle: trust repo truth, keep scope tight, and verify with a rerun.

When to Use

• The user asks for formatting, fmt, format, or lint cleanup
• A code change is done and needs a final style pass before review or commit
• A mechanical change produced noisy diff that should be normalized by the repo's existing toolchain

When Not to Use

• This is not for semantic refactors or behavior changes
• This is not for introducing a new formatter or lint configuration
• This is not for full-repo reformatting unless the user explicitly requests that scope

Inputs

• Target scope: staged files, unstaged files, explicit file list, or explicit directory
• Relevant languages in scope
• Verification commands available in the repository

Procedure

1. Baseline the scope

   • Record git status --short.
   • Default to changed files only unless the user requested broader scope.
   • Resolve the target file set before running any formatter.

2. Detect the repo toolchain

   • Prefer repository scripts and checked-in config over ad hoc commands.
   • Use the repo's existing formatter/linter stack:
     • JS/TS: package.json, prettier, biome, eslint
     • Python: pyproject.toml, isort, black, ruff, flake8, pre-commit
     • C/C++: .clang-format, optional .clang-tidy
     • Shell: shfmt, shellcheck if already present
     • Markdown: prettier/markdownlint only if the repo already uses them

3. Run cleanup in a fixed loop

   • Use formatter -> lint/check -> lint --fix -> final check.
   • Prefer repository entrypoints over raw tool invocations.
   • Keep execution scoped to the chosen files whenever the toolchain supports it.

4. Control blast radius

   • If the formatter expands the diff far beyond the requested scope, stop and explain the tradeoff.
   • Offer a scoped pass vs. a full-repo normalization pass instead of silently widening scope.

5. Verify

   • Re-run the lightweight checks after fixes.
   • Confirm that the second formatter run produces no additional diff.
   • If the repo has a canonical lint or test command for style verification, run that command and report the result.

Playbook as Authority

When the target repo vendors this playbook, prefer these references for style judgment:

• 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

• Scope: actual files/directories/languages processed
• Toolchain: repo configs and commands used
• Commands: execution order
• Changes: modified files plus diff-size summary
• Remaining: unresolved lint/style issues plus why they remain

Success Criteria

• Style cleanup stays within the requested or agreed scope
• The second formatter run produces no additional diff
• Verification commands pass, or any remaining exception is explicitly explained
• No semantic behavior change is introduced

Failure Handling

• If the repo lacks a formatter/linter, say so and fall back to minimal manual cleanup only with clear limits
• If tools are missing locally, report the missing dependency and stop before inventing a new toolchain
• If two configured tools conflict, follow checked-in repo config and surface the conflict instead of papering over it
• If cleanup would require wider scope than requested, stop and ask for approval