tidy-first

Guides small reversible code tidyings separated from behavior changes using Kent Beck's Tidy First approach.

1|Updated May 21, 2026
One-click install
npx skills add https://github.com/vnovakovits/claude-skills --skill tidy-first-vnovakovits
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: tidy-first
Source: https://github.com/vnovakovits/claude-skills/tree/main/plugins/engineering-practices/skills/tidy-first
Command: npx skills add https://github.com/vnovakovits/claude-skills --skill tidy-first-vnovakovits

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When you face messy code and need to make a behavior change, it is unclear whether to clean up first, after, later, or never — and mixing structure changes with behavior changes in one commit makes reviews, reverts, and debugging harder. This Skill provides a decision framework and a catalog of small, safe structural changes to resolve that. ## Core Features & Use Cases - Tidyings Catalog: Fifteen small, reversible structure changes such as guard clauses, explaining variables, extract helper, dead code deletion, and reading order. - Four Timings Framework: Decide for each tidying whether to tidy first, after, later, or never, based on risk, scope, and economics. - Economic Design Reasoning: Frame design decisions as investments using coupling, cohesion, optionality, and discount rate. - Use Case: You are about to fix a bug in a tangled method. The Skill helps you extract a helper and add guard clauses as separate tidy: commits first, then make the behavior change with green tests on both sides. ## Quick Start Ask Claude to review this messy method and suggest which tidyings to apply before making my behavior change.

Frequently Asked Questions about tidy-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I decide whether to refactor before or after a behavior change?▼

Use the four timings framework: tidy first when the change is risky without it, tidy after when the behavior change exposed the mess, tidy later as a separate commit under time pressure, or never tidy code about to be deleted. The decision is when, not whether.

What is the difference between a tidying and a refactoring?▼

A tidying is the smallest structural change you can make, taking minutes and fully reversible, such as a guard clause or explaining variable. If it takes more than a few minutes, it is a refactor, which belongs to larger catalogs like Fowler's Refactoring.

Should structure changes and behavior changes be in the same commit?▼

No, never mix them in one commit. Mixing makes review harder, reverts risky, and debugging ambiguous. Structure changes get their own commits labeled like `tidy: extract function`, with green tests on both sides.

When should I not clean up messy code?▼

Skip tidying when the code is about to be deleted, sits in a corner you will never revisit, or the cleanup is aesthetic rather than economic. Track deliberately untidied mess so it does not disappear from memory.

Why is software design described as an economic activity?▼

Every design decision is an investment whose value includes the future options it preserves. Reversible decisions are cheap, irreversible ones should be deferred, and the benefit of a tidying must exceed its cost discounted for time and risk.