# Tidy

> Refactors production code with test coverage using a TDD workflow that applies approved refactorings one at a time, gates each on passing tests, and commits or reverts accordingly.

- Skill: `sdiamante13/tidy` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add sdiamante13/tidy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sdiamante13/tidy/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Refactoring, Testing & QA
- Tags: Code Quality, Git Commit, Refactoring, Tdd, Test Driven Development
- Author: SDiamante13 (https://skillmd.com/u/sdiamante13)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/sdiamante13/tidy

---


# TDD Production Code Refactoring Process

STARTER_CHARACTER = 🟣

**NEVER** make changes to Test code in this process.

This process is for refactoring production code with test coverage.

## Initial Setup

1. **Locate Test File Proactively**
   - If user provides a file path, search for its test file using common patterns:
     - `filename.test.ext`, `filename.spec.ext`
     - `__tests__/filename.ext`
     - `tests/filename.ext`
     - Mirror path with `/test/` instead of `/src/`
   - Use Glob and Grep to search multiple patterns in parallel
   - If multiple test files found, show options and ask which one
   - If no test file found, inform user and ask them to provide the test file path
   - **Only ask user if ambiguous or not found** - otherwise proceed automatically

2. **Verify Tests Pass**
   - Run the test suite to establish baseline
   - If tests fail initially, stop and report to user

3. **Scan for Refactoring Opportunities**
   - Read the production code file thoroughly
   - Identify ALL refactoring opportunities by priority:
     1. Dead code (commented code, unused variables)
     2. Poor names (unclear variables/methods)
     3. Long methods (> 25 lines)
     4. Duplication (repeated code blocks)
     5. Complex conditionals (nested ifs, no guard clauses)
     6. Unnecessary locals (single-use variables)
     7. Unused imports
   - **Present numbered list** of all findings to user
   - **Ask user which ones to proceed with** (e.g., "all", "1-5", "2,4,7")
   - Wait for user confirmation before starting refactoring

## Refactoring Loop

The approval is interactive and **stays here** (Initial Setup step 3): you present the
numbered findings, ask which to proceed with, and wait for user confirmation. Only the
deterministic apply → green-gate → commit/revert loop is encoded as a **Workflow**, so the
strike cap, green gate, and exact commit-message format run reliably instead of by prose.

Once the user has confirmed the subset, invoke the `Workflow` tool with the bundled script,
passing the human-approved refactor list (in priority order):

```
Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tidy/workflow.js",
  args: {
    refactors: ["<approved refactor 1>", "<approved refactor 2>", ...],  // priority order
    testCommand: "<how to run the suite>",   // optional; agent infers if omitted
    productionFile: "<path>",                 // optional; the file being tidied
    testFile: "<path>"                        // optional; NEVER modified
  }
})
```

For each approved refactor the workflow runs:

1. An agent applies **only that one** refactoring (one at a time, in priority order) to
   **production code** — it **NEVER touches test code** — and returns the diff.
2. A gate agent (Haiku) runs the test suite and returns `{ passed, output }`.
3. If `passed === true`: commit with message format `"- r <refactoring>"` (quotes must
   include the - r). The loop **does not commit until the gate reports `passed === true`**.
4. If tests fail: revert this attempt's changes and retry — up to **three** attempts.

It returns `{ total, attempted, committed, halted, outcomes }`, where each outcome carries
`{ index, refactor, committed, commitMessage, attempts, halted }`. Give a brief status
update after each refactor from the returned outcomes.

**Stop conditions:**
- If a refactor fails three times (the workflow halts and returns `halted: true`)
- If no further refactoring opportunities found
- Pause and check with user

When the workflow returns `halted: true`, **pause and check with the user** before doing
anything else — report which refactor failed and its attempt output; do not continue to the
next refactor on your own.

## Code Style Guidelines

- Prefer self-explanatory, readable code over comments
- Use functional helper methods for clarity
- Remove comments and dead code
- Extract paragraphs into methods
- Use better variable names
- Remove unused imports
- Remove unhelpful local variables
- Methods should be small and focused (ideally < 25 lines)

## Common Refactorings (in priority order)

1. **Remove dead code** - commented code, unused variables
2. **Better names** - rename unclear variables/methods
3. **Extract methods** - break up long methods
4. **Remove duplication** - DRY principle
5. **Simplify conditionals** - reduce nesting, use guard clauses
6. **Remove unnecessary locals** - inline single-use variables
7. **Clean imports** - remove unused imports