tidy-code

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.

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