Overview

Enforces methodical problem-solving by reverting to last known working state and reimplementing step-by-step instead of trying to fix accumulated broken changes.

Core Philosophy

Reimplement, don't fix the mess

When something breaks after multiple failed fix attempts:

Stop trying to fix forward
Revert to last known working state
Understand what worked and why
Reimplement the needed change ONE step at a time
Verify each step before proceeding

When to Use This Skill

Trigger conditions

2+ failed fix attempts for the same issue
"This should work but doesn't" situations
Pipeline failures persisting across multiple commits
User says "the old version worked fine"
Complex accumulated changes with unclear impact

Red flags requiring this skill

Making assumptions about root cause without verification
Blaming "pre-existing issues"
Adding more changes to fix previous changes
Not testing locally before committing

Systematic Process

Phase 1: Identify Working Baseline

# Find last known working state
git log --oneline -20
git show origin/beta:path/to/file.sh  # Check beta/main branch
git diff origin/beta -- path/to/file.sh  # What changed?

# Verify baseline works
git stash
git checkout origin/beta -- path/to/file.sh
# Test it - does it work?

Questions to answer

What was the last commit where this worked?
What branch has a working version? (beta, main, prod)
What specific files/scripts were working?

Phase 2: Compare Current vs Baseline

# Get exact differences
git diff baseline..current -- path/to/file.sh

# Understand each change
# For EACH diff hunk, ask:
# - Why was this changed?
# - What problem was it trying to solve?
# - Did it actually solve that problem?

Document findings

List every change made
Note which changes were necessary
Note which changes broke things
Identify assumptions that were wrong

Phase 3: Revert to Baseline

# Hard revert to working state
git checkout origin/beta -- path/to/file.sh
git add path/to/file.sh
git commit -m "Revert to working baseline from beta"

# Verify baseline works
./test-locally.sh
# Must pass before proceeding

Critical: Don't proceed until baseline is verified working.

Phase 4: Reimplement ONE Change at a Time

For each needed change

Make ONE small change

# Example: Replace sed with awk in ONE function
# Don't change 5 things at once

Test locally immediately

./run-generation-script.sh
terraform validate
# Must pass before committing

Commit if working

git add changed-file.sh
git commit -m "Replace sed with awk in function X"

If it breaks, revert immediately

git reset --hard HEAD~1
# Try different approach or understand why it broke

Repeat for next change

Phase 5: Verify Complete Solution

# Run full test suite
make test
terraform validate

# Compare with original broken state
# Did we achieve the goal without breaking things?

# Push only after local verification
git push

Verification Checklist

Before committing ANY change:

Tested locally and passes
Compared output with baseline (no unexpected differences)
Understood why this change is needed
Change is minimal and focused
Can explain what would break if this change was wrong

Anti-Patterns to Avoid

DON'T

❌ "Let me try one more fix" (revert instead)
❌ "This is probably a pre-existing issue" (verify with baseline)
❌ "The logic should work" (test it, don't assume)
❌ Change 5 things and hope one fixes it
❌ Commit without local verification
❌ Blame the user's code/environment

DO

✅ "Let me check what worked in beta"
✅ "Reverting to baseline first"
✅ "Testing this one change locally"
✅ Make ONE change, verify, commit
✅ Test before every commit
✅ Take responsibility for breakage

Examples

Example 1: Terraform Generation Scripts

Broken approach (Example 1)

# Made 10 changes trying to "optimize" variable filtering
# Each fix broke something new
# Spent day+ debugging

Baseline approach (Example 1)

# Check beta branch - does it work?
git show origin/beta:terraform/build-module.sh > /tmp/beta-version.sh
bash /tmp/beta-version.sh  # Verify it works

# Revert to beta version
git checkout origin/beta -- terraform/build-module.sh

# Now reimplement ONLY what's needed (e.g., sed→awk for portability)
# One function at a time, test each change

Example 2: Pipeline Failures

Broken approach (Example 2)

# Assume it's a CI environment issue
# Try 5 different "fixes" based on guesses
# Each creates new errors

Baseline approach (Example 2)

# Find last passing pipeline
git log --oneline | head -20
# Check what changed since then
git diff <last-passing-commit>

# Revert suspicious changes
# Test locally before pushing

Commands

# Find working baseline
git log --oneline --all | grep "known working feature"
git show origin/beta:path/to/file

# Compare with baseline
git diff origin/beta -- path/to/file
git diff <working-commit> -- path/to/file

# Revert to baseline
git checkout origin/beta -- path/to/file
git checkout <working-commit> -- path/to/file

# Test locally
terraform validate
mix test
yarn test

# Verify no changes after running script
git diff  # Should be empty if script is idempotent

Remember

Reimplement, don't fix - Start from working state
One change at a time - Test each change immediately
Local verification first - Never commit untested changes
Baseline is truth - If baseline works, your changes broke it
Stop digging - After 2 failed fixes, revert and rethink
Question assumptions - Verify, don't assume
Take responsibility - Your changes, your bugs

📖 baseline-restorer