tidy-code

---
name: "tidy-code"
description: "Review the codebase against the 16 tc-* structural-quality categories and produce one consolidated plan a downstream agent or human can execute. The review is read-only. The state file is your own scratch for resuming — not for human review. Mirror the four phases in the host's todo tool."
license: "MIT"
---

Review the codebase against the 16 tc-* structural-quality categories and produce one consolidated plan a downstream agent or human can execute. The review is read-only. The state file is your own scratch for resuming — not for human review. Mirror the four phases in the host's todo tool.

## Non-negotiables (read first)

- **Never modify source files.** The only files this skill writes are the state file and the final plan.
- **Explicit invocation only.** Run via `/tidy-code`; never auto-activate from a natural-language request.
- **Classify every finding** FALSIFIABLE (cites a specific snippet on a specific line that Grep can confirm) or OPINION (the evidence is interpretation).
- **Grep-verify every falsifiable citation before it enters the draft.** No match, or a match at a different line, drops the finding.
- **Depth 1.** Exactly one adversarial-review round. The reviewer never re-runs the file-review pass.
- **Single output file.** The final plan is the only user-facing artifact; surface only its path.

## Excluded paths

Skip discovery and review in:

- Dot-directories: `.git/`, `.venv/`, `.agents/`, `.claude/`, IDE/agent scaffolding
- `node_modules/`, `vendor/`, `bower_components/`, any `*/third_party/*` or `*/vendor/*`
- Build outputs: `dist/`, `build/`, `target/`, `out/`, `coverage/`, `__pycache__/`, `.next/`, `.cache/`
- Non-source files: config (JSON/YAML/TOML), markdown, lockfiles, minified assets, images, fonts
- Generated code (`@generated`, `DO NOT EDIT`, and kin), migrations, `.d.ts` files, scripts under 20 lines
- Anything in `.gitignore` — treat it as authoritative

## State file

Working state lives at `.agents/local/state/tidy-code-YYYY-MM-DD.md` (date from `date +%Y-%m-%d`). If today's file exists and is fully checked, append `-2`, then `-3`. It is your own scratch — gitignored, never shown to the user, never committed.

**On start:** create `.agents/local/state/` if missing, then glob `.agents/local/state/tidy-code-*.md`. If the newest file has unchecked items, resume against it; otherwise create a new one. Delete the file to force a fresh run.

```markdown
# tidy-code — 2026-07-17

## Batch 1
- [ ] src/auth/session.ts
- [ ] src/auth/token.ts (test)

## Findings draft
- [tc-05] Silent Failure — src/auth/session.ts:88 — sev:high — grep:`except:` — bare except hides auth failures → raise or log explicitly
```

Mark files `[x]` as their worker returns. Workers never write the state file — concurrent writes corrupt it.

## Phase 1 — Discovery (mechanical, no subagents)

Enumerate source files inline with Glob or a shell lister — prefer `rg --files`, falling back to `fd --type f`, then plain `find . -type f`, when a tool isn't installed — honoring the exclusions above. Mark each file app or test (test = `*.test.*`, `*.spec.*`, `*_test.*`, `test_*`, and language equivalents; non-test files under `/tests/` such as factories, fixtures, and helpers count as app). If no app files remain, stop with a user-facing error; if more than 1000, ask the user to scope the review (e.g., a subdirectory) first.

Group files into batches of 8–12 per worker (a repo under 20 app files is one batch), write the checklist to the state file, and go straight to Phase 2 — do not stop, summarize, or ask.

## Phase 2 — Review (parallel by batch)

Dispatch one worker subagent per batch — up to 5 concurrent, all of a wave's Agent calls in a single message so they run in parallel. **Worker:** `subagent_type: general-purpose`, `model: haiku` (the host's cheap-model alias — never a pinned version). Brief each worker with its file list (app/test marked), the finding-line format below, and the inline guardrail: **read-only — never modify any file; report findings only.** Workers run from the user's project root, so before dispatching, expand every `references/…` path in their briefs to its absolute path under this skill's directory.

Each worker:

1. Reads `references/principles-quick-ref.md` first; loads a per-category reference only when a candidate for that ID appears; loads `references/severity-rubric.md` when classifying severity.
2. Reads its batch with parallel tool calls and reviews app files against all 16 categories. Test files get **tc-09, tc-03, and tc-13 only** — skip the rest.
3. Applies the falsifiability gate with its own Grep calls: FALSIFIABLE findings carry the verified pattern; unverifiable citations are dropped, not reported.
4. Verifies each suggested rewrite resolves the violation without introducing a new one. One revision attempt; if still unverifiable, the suggested fix becomes the sentinel `[Suggested rewrite could not be verified — manual rewrite required]`.
5. Returns findings as compact one-line bullets (OPINION findings omit `grep:`):

```
- [tc-05] Silent Failure — src/api/client.py:88 — sev:high — grep:`except:` — bare except hides auth failures → raise or log explicitly
```

If a worker fails or returns nothing parseable, re-dispatch its batch once; if it fails again, leave its files unchecked and note them when done.

You (the orchestrator) append each worker's findings to the state file's draft and tick its files. Dedupe on append: same category at the same file:line keeps one; when one piece of evidence supports several categories (a `UserManager` that is both tc-04 and tc-09), keep the higher-severity finding and note the others in its line.

Per-category references: tc-01 `composition-over-inheritance.md` · tc-02 `dependency-injection.md` · tc-03 `guard-clauses.md` · tc-04 `single-responsibility.md` · tc-05 `fail-fast.md` · tc-06 `least-surprise.md` · tc-07 `tell-dont-ask.md` · tc-08 `immutability.md` · tc-09 `naming.md` · tc-10 `functional-core-imperative-shell.md` · tc-11 `magic-numbers.md` · tc-12 `duplicate-logic.md` · tc-13 `comment-debt.md` · tc-14 `type-escape.md` · tc-15 `query-in-loop.md` · tc-16 `unsafe-sink.md` (all under `references/`).

## Phase 3 — Adversarial review (one round)

Dispatch one reviewer subagent on the host's default model with the full findings draft, the repo root, and the prompt in `references/adversarial-review-prompt.md`. The reviewer re-runs cited greps itself, challenges false positives, severity inflation, and unactionable rewrites, flags missing findings, and returns a KEEP/REVISE/DROP verdict list.

Apply the verdicts to the draft yourself: delete DROPs, fold in REVISEs, append grep-verified additions. Depth is 1 — never dispatch a second round, whatever the verdict mix.

## Phase 4 — Report

Load `references/final-plan-format.md` and write the reviewed findings as one self-contained plan:

1. If `docs/` exists at the repo root → `docs/YYYY-MM-DD-tidy-code-plan.md`.
2. Else → `YYYY-MM-DD-tidy-code-plan.md` at the repo root.

Findings still carrying the sentinel go in `<manual_review>`. Your reply to the user names only this path — never the state file or any intermediate detail.

## Failure modes to avoid

- Do not apply the full catalog to test files — tc-09/tc-03/tc-13 only. tc-02 and tc-10 flag side-effectful setup that is normal in tests.
- Do not treat `/tests/` factories, fixtures, or helpers as test files — they are app code, full catalog.
- Do not defer comment findings to another skill. Comment existence and TODO/FIXME/HACK/XXX markers are owned here (tc-13; allowlist: docblocks, linter directives, non-obvious why).
- Do not report cross-file duplicate logic — out of scope (see `principles-quick-ref.md` § Scope boundaries).
- Do not present a cross-file rename with blast radius > 5 files as safe — mark the finding `blast radius: N files — confirm before applying` (tc-09).
- Do not add confidence, difficulty, or risk scores — this skill reports findings; it does not rank them.
- Do not pad thin batches to look thorough. Zero findings for a clean file is a valid result.

## Done

The job is done when every state-file checkbox is ticked and the plan is written. Reply with the plan path and a one-line summary of finding counts by severity. Do not commit anything, run build or test commands, or delete the state file.