diff --git a/skills/style-cleanup/SKILL.md b/skills/style-cleanup/SKILL.md index a41e4ccb..cdddb193 100644 --- a/skills/style-cleanup/SKILL.md +++ b/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 -- ` and `git diff -- ` 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