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

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