In the last lesson you audited the shape of your project — one duplicate, one oversized file, one unclear ownership boundary, one dependency to investigate — and you deliberately did not rewrite anything. That restraint bought you something: a clear map of where the pain is.

Now you learn to improve one spot without freezing the project or asking an AI to rewrite everything.

What a seam is

A seam is a place where one responsibility can be separated from another with a small, testable change.

Four examples make the idea concrete:

• Extract date formatting out of a UI component into a small helper the component calls.
• Move source validation into one function instead of scattering checks across three files.
• Replace two duplicate API calls with one shared client both callers use.
• Remove a dead feature after confirming — by searching imports and running the project — that nothing references it.

Each seam has the same property: you can describe the behavior before and after, and the user should notice no difference. The shape improves. The behavior stays put.

Refactoring is shape, not behavior

Refactoring means changing the internal shape while preserving the intended user behavior. It is not a visual redesign. It is not a new feature. And it is definitely not a license for an AI to change every file it can reach.

That boundary is what separates a safe cleanup from a risky rewrite. "Make the dashboard cleaner" invites the model to rename files, swap libraries, and reinterpret requirements. "Move the freshness rule into one function; the badge, export, and alert must produce exactly the same output for the same input" gives the model a seam, a behavior to preserve, and a way to be proven wrong.

Write that distinction into every cleanup task. If the user-visible outcome changes, it is not a refactor — it is a feature or a fix, and it needs its own acceptance checks.

The safe cleanup loop

Run this loop exactly in order, one seam per pass:

Name one pain → map current behavior → choose one seam
  → add or confirm a behavior check → make one structural change
  → compare result → save a checkpoint → stop

Name one pain. Pick one line from your PROJECT-SHAPE.md. "Three copies of the freshness rule disagree."

Map current behavior. Before touching code, write down what the system actually does today — including the inconsistencies. The citation card says 30 days, the export says 21, the alert says something else. That map is your baseline.

Choose one seam. One function, one duplication, one extraction. Not the file, not the module — the seam.

Add or confirm a behavior check. A repeatable check of expected behavior: a test, a preview walkthrough with known inputs, a script comparing outputs. For the freshness rule, that might be five sample sources with known dates and the expected "fresh" or "stale" answer for each.

Make one structural change. Move the logic behind one owner. Nothing else.

Compare result. Run the same check. Same inputs, same outputs — except for the inconsistency you deliberately resolved and wrote down.

Save a checkpoint. A recoverable saved version of the working files, with a note about what changed and what remains. Part X will teach the formal machinery for this — version history, branches, and review. For now, the habit is: never make a structural change you cannot return from.

Stop. This step belongs in the loop on purpose. A successful cleanup creates temptation — "while I am here, let me fix the date library, the giant file, and the dead code too." Do not. A focused refactor that keeps going becomes a risky rewrite with no stable behavior to compare against. File the next seam as a new task and start the loop again.

Before and after: one owner for the fresh rule

Here is what one pass looks like on the research dashboard:

Before: citation card, export script, and alert job each decide
whether a source is "fresh."

After: one source-status function owns the rule; each surface
asks it for the answer.

You did not need to know the ideal architecture upfront. You needed to identify the current behavior, preserve it, and make the ownership clearer in one small step. Next week, if the product team changes "fresh" from 30 days to 14, there is exactly one function to change and one check to run.

The events finder gets the same treatment at smaller scale: before, two distance calculations for "near me" disagree at the boundary; after, one distance helper owns the rule and both the list and the map call it.

Why shape controls AI cost

Here is the connection back to everything Part IX has taught about context: a messy repository creates a messy prompt.

When one small change requires loading ten huge files, several contradictory instructions, and months of chat history, context costs rise and model accuracy falls. The model cannot tell which copy is authoritative, so it guesses — or copies the wrong one again. Improving the project's shape also makes AI work cheaper and easier to direct: smaller files, one owner per rule, fewer contradictions to load into the window.

Every seam you repair is therefore two wins: the code is easier to change, and the next AI session needs less context to change it correctly.

Part X gives you the safety system that makes structural work routine — saved history, branches for isolated attempts, and review before anything merges. This lesson teaches the reasoning; the next part teaches the tools. Do not attempt a large refactor without that safety net in place.

Practical exercise: write a refactor card

Create REFACTOR-CARD.md. Ask the AI to inspect and propose options — do not ask it to refactor until the card is approved.

# Refactor card: single freshness owner

- Pain: three surfaces compute "fresh" with different thresholds.
- Current behavior: card uses 30 days, export uses 21, alert uses inline check (see files/lines).
- Seam: extract one `isSourceFresh(source)` function; point all three callers at it.
- Behavior that must NOT change: same badge/export/alert output for the five sample sources, except export moves 21 → 30 (approved).
- Evidence to run: sample-source check plus preview of brief page and export.
- Stop point: freshness seam only. Date library, giant brief file, and dead component are separate cards.

Let the AI inspect the named files and propose two options with tradeoffs. You pick one. Then — and only then — authorize the single structural change inside the agreed boundary.

Finish line: a refactor card and an approved, one-seam plan. No code changes are required to complete this lesson.

Verify: can you point to the pain, the current behavior, the seam, the unchanged behavior, and the evidence? If any field is blank, the card is not ready for implementation.

Common failure mode: prompting "clean up the codebase" and receiving broad edits with no stable behavior to preserve. Recovery: cancel the broad task, choose one duplication or one function with one observable output, and write the card for that alone.

Check your understanding

1. What is a seam, and what makes your four examples seams rather than rewrites? 2. How is refactoring different from a redesign or a feature? 3. Recite the cleanup loop. Why is "stop" an explicit step? 4. Why does a messy repository make AI assistance more expensive and less accurate? 5. Your AI proposes touching six files to "clean things up properly." What do you do?