89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
---
|
|
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
|