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

## 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