Tidy First Skill

Execute structural changes BEFORE behavioral changes, following Kent Beck's Tidy First approach.

What Qualifies as "Structural"?

Structural changes rearrange code WITHOUT changing behavior:

✅ Structural (Tidy First):

• •Rename variables, functions, classes for clarity
• •Extract methods/functions to reduce duplication
• •Move code to different files/modules for better organization
• •Reorder code for readability
• •Add type annotations
• •Split large functions into smaller ones
• •Consolidate duplicate code

❌ NOT Structural (Behavioral):

• •Add new features
• •Fix bugs
• •Change logic or algorithms
• •Modify API contracts
• •Add/remove parameters
• •Change return types

The Tidy First Process

1. Capture Baseline

Before making ANY structural change, run tests to capture baseline:

# Run all tests
npm test

# Verify TypeScript compilation
tsc -b --noEmit

All tests MUST pass before proceeding. If tests fail, fix them first.

2. Make ONE Structural Change

Make exactly ONE type of structural change at a time:

• •Rename OR extract OR move (not multiple types at once)
• •Keep the change focused and small

Examples of ONE change:

• •Rename processData to validateUserInput across all files
• •Extract duplicate validation logic into validateInput() function
• •Move all repository interfaces to domain/repositories/ folder

3. Verify No Behavior Change

After the structural change, run tests again:

# Run all tests
npm test

# Verify TypeScript compilation
tsc -b --noEmit

Tests MUST still pass - this proves you didn't change behavior.

If tests fail:

• •❌ You accidentally changed behavior
• •⚠️ Revert the change and try again more carefully

4. Commit Separately

Commit the structural change with refactor: type:

git commit -m "refactor: rename processData to validateUserInput for clarity"
git commit -m "refactor: extract duplicate validation into validateInput"
git commit -m "refactor: move repository interfaces to domain layer"

Critical Rules

• •✅ ALL structural changes BEFORE behavioral changes
• •✅ ONE structural change type per commit
• •✅ Tests must pass BEFORE the change
• •✅ Tests must pass AFTER the change
• •✅ If tests fail after, you changed behavior - REVERT
• •✅ Use refactor: commit type for structural changes
• •✅ Never mix structural and behavioral in same commit

Why Separate Structural from Behavioral?

1. •Easier to review: Reviewers can see structure changes vs logic changes separately
2. •Safer: If behavior breaks, you know it's from behavioral commits, not structural
3. •Easier to revert: Can revert behavioral changes without losing structural improvements
4. •Better history: Git history shows clear progression of work
5. •Less risky: Structural changes with passing tests are provably safe

Example Workflow

# WRONG: Mixed structural + behavioral
git commit -m "Add user validation and rename variables"  # ❌

# RIGHT: Separate commits
git commit -m "refactor: rename userData to userInput for clarity"  # ✅
git commit -m "feat: add user validation logic"  # ✅