Scratch Refactoring for Code Understanding

Intent

scratch refactoring is a throwaway code comprehension technique. you restructure unfamiliar code freely, without writing tests or worrying about production standards, to build a mental model of its structure and behavior. once understanding emerges, you discard the refactored code and keep only the learning notes. use this skill when passive reading is not producing clarity and you need to understand code structure before you can change it safely, write characterization tests, or make architectural decisions.

Inputs

input	required	description
target code path	yes	file(s), class(es), or method(s) the developer wants to understand. ask for clarification if vague ("the billing module" is too broad; "the calculateInvoice() method" is right-sized).
learning goal	yes	the specific question to answer (e.g. "what are the phases of this algorithm?", "what does this class own vs. delegate?", "why does this method have all these parameters?"). elicit via conversation if not provided. default: "identify top-level responsibilities and relationships."
vcs clean state	yes	confirm the working tree is clean. no uncommitted production changes. if the tree is dirty, either stash production changes or abandon the skill until the tree is clean.
current understanding	no	what the developer already knows about the code. prevents re-explaining existing knowledge and focuses the session on opaque areas.
vcs type and branch base	no	git is standard; confirm the base branch (usually main or develop) before creating scratch branch.

Procedure

step 1: verify vcs safety and isolation

establish a scratch workspace so exploratory changes can be discarded cleanly.

inputs: vcs access, working tree status

action: run one of:

# preferred: create a scratch branch
git checkout -b scratch/understand-<target-name>
# example: git checkout -b scratch/understand-calculate-invoice

# fallback: if branch creation is blocked, stash current state
git stash push -m "scratch: pre-exploration state"

outputs: isolated branch or stash, confirmed in git status or git branch output

why: the discard step (step 5) only works cleanly if you can delete the branch or pop the stash. without vcs isolation, exploratory changes bleed into production code. this is the only safety net.

edge case: if the working tree is dirty and the developer refuses to stash, stop here. do not proceed. a dirty tree makes discarding exploration unsafe.

step 2: state learning goal and scan target code

read the target code with fresh eyes. restate the learning goal as a concrete question. record it.

inputs: target code path, learning goal (from inputs), developer's current understanding

scan for:

• methods over 20 lines (candidates for structural understanding via extraction)
• variables with single letters or cryptic names (signal unclear intent)
• nested conditionals or compound boolean expressions (hidden logic)
• class fields that cluster around different concepts (hidden cohorts or responsibilities)
• methods that touch different subsets of fields (signal of hidden roles within the class)

action: read the code deliberately. if the learning goal was vague ("help me understand this mess"), restate it as a concrete question: "what are the entry points and decision points?" or "what state does this class actually manage?" or "does this method have hidden side effects?"

outputs: concrete learning goal (one sentence), scan notes (can be mental or jotted on paper/editor), target code range confirmed

why: a stated goal acts as a stopping condition. without it, scratch sessions drift into endless tinkering. the goal tells you when to move to step 4 (write learning notes) instead of continuing to refactor.

edge case: if the developer cannot state a goal after reading the code, use the default: "identify the top-level responsibilities of this code and the relationships between them."

step 3: refactor freely without tests

manipulate the code structure to make hidden intent visible. do not stop to write tests, worry about performance, or meet code-review standards. speed and visibility are the only goals.

inputs: target code, learning goal, isolated scratch workspace

common refactoring moves (in order of usefulness):

1. extract method: pull a block of code into a named method. the method name becomes a label for what that code does. example: extract lines 45-67 into checkInventoryAvailability() to reveal that a mystery block handles inventory.

2. rename variable or method: replace x, temp, result, or data with a name that reflects what you now understand. example: rename acc to invoiceSoFar to reveal it accumulates across iterations.

3. inline variable: collapse a one-use variable to see the expression directly. example: if eligible = user.isPremium && order.total > threshold, inline eligible to see the conjunction.

4. split conditional: break a compound condition into named booleans. example: replace if (x > 10 && y < 5 && z.status == 'active') with isExpensive = x > 10; isLowInventory = y < 5; isActive = z.status == 'active'; if (isExpensive && isLowInventory && isActive).

5. reorder methods: group related methods together in the class. cohesive methods cluster. scattered references reveal hidden responsibilities.

6. introduce temporary comments: mark the phases or logic blocks with comments that name what each phase does. example: // phase 1: validate input and fetch dependencies above a block, // phase 2: compute base amount above the next block.

action: apply moves until the code structure is no longer opaque. you do not need to refactor the entire file, only the parts that answer the learning goal.

outputs: refactored code on scratch branch (temporary), your emerging understanding (mental model)

why: the normal rule "do not refactor without tests" prevents regressions in production code. in a scratch exploration that will be discarded, the risk is zero. removing the constraint allows rapid structural manipulation without sealing each change with a test. speed unlocks comprehension.

edge cases:

• if a refactoring breaks compilation or a syntax error appears, fix it immediately so the code remains readable. the goal is clarity, not correctness, but the code must not be syntactically broken.
• if you extract a method and the extracted code turns out to be wrong or misleading, re-inline it or rename it. trust your emerging understanding; the code is a tool, not the goal.
• if you discover the code is more complex than expected and refactoring is not yielding clarity, pause and write learning notes on what you have learned so far. complexity itself is a learning signal.

step 4: write learning notes during and after refactoring

capture what you learn as understanding emerges. do not save this for the end. notes are the deliverable; refactored code is not.

inputs: emerging understanding from step 3, learning goal, current state of refactored code

action: save a file (e.g., learning-notes.md in the scratch branch or a temporary location) and fill in:

# learning notes: <target code path>
date: <YYYY-MM-DD>
question: <learning goal from step 2>

## structure discovered
<plain-English description of what you now understand: top-level phases, responsibilities, cohorts, entry points, decision points, collaborators>

## surprises
<anything counterintuitive, unexpected, or that contradicted your initial assumption>
<any false assumptions you held and corrected during the session>

## dependencies and risks
<anything that propagates changes widely across the codebase>
<anything this code depends on that is not obvious from reading it alone>
<fragile patterns or implicit contracts>

## next-step recommendation
<what to do next: write characterization tests for behavior X, apply production refactoring Y, investigate coupling Z, etc.>

outputs: learning-notes.md with completed sections

why: learning notes are the only artifact worth keeping. if you discard the refactored code but have written down what you learned, you retain all value. if you keep the refactored code without notes, you have a dangerous artifact (structure shaped by discovery order, not production design) and no portable insight.

example notes:

# learning notes: CustomerManager class

question: what responsibilities does this class own?

## structure discovered
three hidden roles: user identity management (fields userId, email, profile), subscription lifecycle (fields subscriptionStatus, planId, renewalDate, methods subscribe/cancel/renew), notification dispatch (methods sendConfirmation/sendReminder). each role operates on a separate cohort of fields. subscription methods are 40% of the class.

## surprises
the renew() method reads a hardcoded configuration object (not passed in). the sendConfirmation() method has a side effect (it updates the user's lastNotificationTime field, which is not obvious from the method name).

## dependencies and risks
the class depends on a global PaymentGateway singleton, which means testing is hard and this class is coupled to global state. the notification dispatch calls an external email service that can time out; there is no retry logic.

## next-step recommendation
write characterization tests for the subscription renewal behavior (including the global config read). plan to extract a SubscriptionHandler class to reduce CustomerManager to a single role.

step 5: discard scratch refactoring and verify clean state

delete the scratch branch or pop the stash. the refactored code is temporary; the learning notes are permanent.

inputs: scratch branch or stash, learning notes file (saved), confirmation that you have extracted all insights

action: run one of:

# if you used a scratch branch:
git checkout main    # or your base branch
git branch -D scratch/understand-<target-name>

# if you used stash:
git checkout -- .
git stash pop

then verify:

git status           # should show "working tree clean"
git log --oneline -1 # should show your base branch, not the scratch branch

outputs: clean working tree, original code restored, learning notes file retained in your document store (not in the repo)

why: feathers is explicit: throw the code away. the scratch structure was shaped by the order of your discoveries, not by production design intent. committing it biases future refactoring by making one particular decomposition feel "already done" and introduces structure that was never evaluated against the full system. the learning lives in your head and the notes; the code belongs in the trash.

edge case: if you cannot delete the branch (permission issue, server lag), abandon it and create a new scratch branch next time. do not proceed to production work until the scratch workspace is confirmed deleted or stashed.

Decision Points

decision 1: should i create a scratch branch or use stash?

• if the codebase supports branch creation and you have permission, use a branch. it is clearer and easier to navigate.
• if you are in a monorepo or branch creation is slow, use git stash. both achieve isolation.
• if the working tree is already dirty with production changes, refuse to proceed. ask the developer to stash production changes first, then create the scratch space.

decision 2: is the learning goal concrete enough?

• if the developer says "help me understand this code", it is too vague. push back: "which question would you like answered? what is confusing?" examples: "what are the phases?", "what does this class own?", "why does this need 8 parameters?", "where does the business logic live?"
• if you cannot elicit a concrete goal after two attempts, use the default: "identify the top-level responsibilities and relationships."

decision 3: should i continue refactoring or move to step 4?

• if your refactorings have answered the learning goal, move to step 4. you are done exploring.
• if you are still unclear after 30 minutes of refactoring, pause and write learning notes on what you have learned so far. complexity itself is information; partial understanding is still progress.
• if you find yourself refactoring code outside the target range ("while i'm in here, let me fix this other thing"), stop and return to the target. scope creep kills scratch sessions.

decision 4: should i keep any of the refactored code?

• no. discard all of it. the refactored code is not production-ready (no tests), was shaped by discovery order (not design), and biases future refactoring. keep only the learning notes.
• exception: if you discovered a bug or obvious defect in the original code (e.g., a null pointer dereference), document it in learning notes and fix it on the main branch in a separate commit with a test. but the scratch refactoring itself is discarded.

decision 5: what if the refactored code was actually better than the original?

• resist the urge to keep it. the refactoring was exploratory; you did not write tests, did not consider the full system impact, and did not get code review. real refactoring, done with tests and full context, may find a better structure. the learning notes preserve what matters. apply the learning in a proper refactoring effort on the main branch, with characterization tests, one seam at a time.

Output Contract

learning notes file (learning-notes.md):

• format: markdown
• location: in your document management system (not in the repo, or in a temporary scratch location that is discarded with the branch)
• contents: answered questions section (learning goal answered), structure description (plain English, no code), surprises, dependencies and risks, next-step recommendation
• success condition: reading the notes three days later, you can recall the code structure and your conclusions without re-reading the original code

refactored code:

• format: source code files on scratch branch
• location: git scratch branch or stash
• contents: not specified (varies by exploration)
• success condition: deleted and confirmed gone before production work continues

vcs state:

• format: git status output
• location: command line
• contents: "working tree clean" or equivalent
• success condition: git status shows no uncommitted changes and git branch shows no scratch branch remaining

Outcome Signal

the skill has worked when:

1. you can answer the learning goal without looking at the code. example: "the method has three phases: validate input, compute base amount, apply adjustments" or "the class has two hidden responsibilities: subscription and notification, which should be split."

2. you have written learning notes that capture structure, surprises, risks, and next steps. the notes are self-contained enough to be useful if you return to the code in three weeks.

3. the scratch branch is deleted and the working tree is clean. git branch does not list the scratch branch. git status shows "working tree clean".

4. you have a concrete next step you can execute. example: "write a characterization test for the renewal behavior" or "extract the subscription logic into a new class using the Extract Class technique" or "investigate why this method depends on global config."

5. you feel confident enough to change the code without breaking it. you understand the structure well enough to write a characterization test, identify change points, or plan a refactoring.

if you have deleted the scratch code but cannot remember what you learned, the outcome signal has failed. writing learning notes is not optional; it is the deliverable. if you kept the refactored code and committed it to main, you have failed to follow the technique; discard it and redo the session on a fresh branch.

Key Principles

1. never commit scratch refactoring. vcs is the safety net, not the feature branch. the scratch branch is a workspace, not a feature branch. refactorings made under comprehension pressure, without tests or full context, introduce structure that was shaped by discovery order, not by production design. committing them biases future real refactoring and introduces untested structure into the codebase. the only safe state is the one you started in; the only artifact worth keeping is the learning notes.

2. a scratch mistake can create a false mental model. cross-check surprising conclusions against the original code. when you refactor freely, you will sometimes make extraction mistakes: a method name that implies the wrong abstraction, a grouping that hides