Scratch Refactoring For Code Understanding

Dev Tools

Guide a developer through throwaway refactoring — restructure code freely without tests to understand it, then DISCARD. Use whenever a developer says 'I don't understand this code', 'this code is too complex to change safely', 'need to read legacy code', 'can't figure out what this does', 'overwhelmed by legacy', 'code archaeology', 'understand before change'. Also activates for 'scratch refactoring', 'throwaway refactoring', 'code comprehension', 'code reading technique', 'feature sketch', 'effect sketch', 'notes on legacy code'.

Install

openclaw skills install bookforge-scratch-refactoring-for-code-understanding

Scratch Refactoring for Code Understanding

When to Use

Use this skill when a developer cannot understand a section of code well enough to change it safely. Scratch refactoring is the right tool when:

Passive reading (scrolling through code) is not producing a clear mental model
The code is too tangled to trace by eye — hidden coupling, deep nesting, mystery variables
You are onboarding to a codebase area with no documentation and no author to ask
A planned change is blocked because the intent of the existing code is unknown

Scratch refactoring is a comprehension technique, not a production technique. It is a complement to characterization tests (which pin down behavior) and effect sketches (which map change propagation). When you need to understand structure before you can even write a characterization test, scratch refactoring is the right first step.

Do not use this skill if:

The code is already understood — skip directly to characterization testing
You are mid-change on a production branch — a scratch exploration on a dirty working tree risks mixing exploration with production edits

Context & Input Gathering

Before starting, collect:

Target code path — the file(s) and class/method range the developer wants to understand. Ask if not provided.
Learning goal — what specific question the developer wants answered. Examples: "What are the phases of this algorithm?", "What does this class actually own?", "Why does this method need all these parameters?" A precise question produces a focused scratch session.
VCS status — confirm the working tree is clean (no uncommitted production changes) or that a stash is in place. A dirty working tree makes discarding the scratch exploration unsafe.
Current understanding — what the developer already knows. This prevents re-explaining what is already clear and focuses the scratch session on the opaque parts.

If the developer cannot state a learning goal, use this default: "Identify the top-level responsibilities of this code and the relationships between them."

Process

Step 1: Verify VCS Safety

Create a scratch branch (preferred) or confirm a clean stash before touching any file.

git checkout -b scratch/understand-<target-name>
# or, if branch creation is not practical:
git stash push -m "scratch: pre-exploration state"

Why: The discard step (Step 5) only works cleanly if the scratch branch can be deleted or the stash popped. Without this isolation, exploratory changes can accidentally survive into production code. The version-control system is the safety net — it must be set up before the exploration begins, not after.

Step 2: Identify Target and Learning Goal

Read the target code with fresh eyes. Scan for:

Methods over 20 lines (candidates for extraction)
Variables with non-descriptive names (candidates for renaming)
Conditional blocks that could be named (candidates for extraction)
Class fields that cluster around different concepts (signals of hidden responsibilities)

Restate the learning goal as a concrete question. Write it down — this becomes the first line of your learning notes.

Why: Without a stated goal, scratch sessions drift. The goal acts as a stopping condition: once you can answer the question, the session is done. This prevents over-investment in the scratch structure.

Step 3: Refactor Freely — No Tests Required

Refactor the target code without writing any tests. Common moves:

Extract Method — pull a block of code into a named method to make its intent visible
Rename Variable / Method — replace cryptic names with names that reflect what you now understand
Inline Variable — collapse a one-use variable to see the expression directly
Split Conditional — break a compound condition into named booleans
Reorder Methods — group related methods together to see cohesion

Do not stop to make the code production-ready. Do not worry about performance, test coverage, or code review standards. The goal is visibility, not correctness.

Why: The normal constraint "do not refactor without tests" exists to prevent regressions in production code. In a scratch exploration that will be discarded, that constraint does not apply. Removing it allows rapid structural manipulation that would otherwise require a full seam-introduction and characterization-test cycle. The speed is the point.

Step 4: Write Learning Notes

As understanding emerges — not at the end, but during the session — write down what you are learning. Do not capture the refactored structure. Capture the insights.

Learning notes template (save as learning-notes.md in a scratch location):

# Learning Notes: <target code>
Date: <today>
Question: <the learning goal from Step 2>

## Structure discovered
<plain-English description of the top-level structure: phases, responsibilities, collaborators>

## Surprises
<things that were unexpected or counterintuitive>
<any false assumptions that were corrected during the session>

## Dependencies and risks
<anything that propagates changes widely, or that the code depends on unexpectedly>

## Next-step recommendation
<what the developer should do next: write characterization tests for X, apply technique Y, investigate Z>

Why: The learning notes are the deliverable, not the refactored code. If you write down what you learned but discard the scratch code, you have everything you need. If you keep the scratch code but write nothing down, you have a dangerous artifact and no portable insight.

Step 5: Discard the Scratch Refactoring

Delete the scratch branch or pop the stash back to the pre-exploration state.

# 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

Verify the working tree is clean before moving to production work.

Why: Feathers is explicit: "Throw that code away." The scratch structure was shaped by the order of your discoveries, not by production design intent. Committing it introduces structure that was never evaluated against the full system, may contain mistakes made during rapid exploration, and — most insidiously — biases future refactoring by making one particular decomposition feel "already done." The insight belongs to the developer's head and the learning notes. The code belongs in the trash.

Inputs

Input	Required	Description
Target code path	Yes	File(s) and class/method to understand
Learning goal	Yes	The specific question to answer (elicit if not provided)
VCS clean state	Yes	Clean working tree or scratch branch before starting
Current understanding	No	What the developer already knows (prevents redundant exploration)

Outputs

Output	Format	Kept or Discarded?
Learning notes	`learning-notes.md`	Kept — the primary deliverable
Scratch refactored code	Modified source files on scratch branch	Discarded — deleted after session

Learning notes template (minimum viable):

# Learning Notes: <target>
Date: <YYYY-MM-DD>
Question: <learning goal>

## Structure discovered
<top-level structure in plain English>

## Surprises
<unexpected findings; corrected false assumptions>

## Dependencies and risks
<what propagates changes widely>

## Next-step recommendation
<characterization tests / technique / investigation to do next>

Key Principles

1. Never commit scratch refactoring — VCS is the safety net, not the deliverable. The version-control system exists so that the scratch branch can be deleted cleanly. Committing exploratory code introduces structure that was shaped by the order of discovery, not by production design intent. The branch is a workspace, not a feature branch.

2. A scratch mistake can create a false mental model — verify 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 a real coupling. If you trust the scratch structure without checking it against the original, you may carry a wrong understanding into production work. Before writing learning notes, cross-check surprising conclusions against the unmodified code (easy to do since the original is one branch switch away).

3. Attachment to scratch structure biases real refactoring — keep the insight, not the shape. A scratch session that ends with "I did the refactoring already, let me just commit it" has failed. The scratch decomposition may be one valid decomposition — but it was found under comprehension pressure, without the full context of the change goal, tests, and system design. Real refactoring, done with tests and full context, will often find a better structure. The learning notes preserve what matters; discarding the code preserves the developer's ability to see that better structure.

Examples

Example 1: Opaque Algorithm in a Billing System

A developer needs to modify a 300-line calculateInvoice() method but cannot determine which lines handle tax calculation versus line-item accumulation versus discount application.

Scratch session:

Create branch scratch/understand-calculate-invoice.
Learning goal: "What are the phases of this method, and where does each phase begin and end?"
Extract blocks into named methods: accumulateLineItems(), applyVolumeDiscounts(), calculateTaxByJurisdiction(), formatInvoiceOutput().
Learning notes record: three-phase structure (accumulate → discount → tax), tax phase reads a hidden configuration object, discount logic has a special case for government accounts.
Delete branch. Learning notes survive.

Result: The developer now knows exactly where to add the new billing adjustment — in the accumulation phase, before discounts — and what tests to write first (a characterization test for the government-account discount case).

Example 2: Class with Tangled Responsibilities

A team inheriting a CustomerManager class (800 lines, no tests) cannot determine what it owns versus what it delegates.