🐛 fix(style-cleanup): preserve scope and git state

skills/style-cleanup/SKILL.md

@@ -3,78 +3,58 @@ name: style-cleanup
 description: 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（整理代码风格 / 格式化）
+# Style Cleanup
 
 ## 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.
+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.
 
-## When to Use
+## Use Boundary
 
-- 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
+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.
 
-## When Not to Use
+## Workflow
 
-- 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
+1. **Fix the scope and preserve Git state**
 
-## Inputs
+   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.
 
-- Target scope: staged files, unstaged files, explicit file list, or explicit
-  directory
-- Relevant languages in scope
-- Verification commands available in the repository
+2. **Resolve authority in this order**
 
-## Procedure
+   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.
 
-1. **Baseline the scope**
+3. **Choose commands from repository evidence**
 
-   - Record `git status --short`.
-   - Default to changed files only unless the user requested broader scope.
-   - Resolve the target file set before running any formatter.
+   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.
 
-2. **Detect the repo toolchain**
+4. **Apply and control the blast radius**
 
-   - 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.
+   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**
 
-   - 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.
+   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
 
-When the target repo vendors this playbook, prefer these references for style
-judgment:
+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`
@@ -83,25 +63,26 @@ judgment:
 
 ## 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
+Report `Scope`, `Authority`, `Commands`, `Git State`, `Changes`, `Verification`,
+and `Remaining`. Include before/after staged state, diff size, idempotence, checks,
+behavior tests, and anything unverified.
 
-## Success Criteria
+## Quick Reference
 
-- 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
+| 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 |
 
-## Failure Handling
+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.
 
-- 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
+## 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