The New Medium — Refactor Workflow

Refactor without a coordination layer is just guessing.

Most modernization efforts fail not because developers can't write clean code — but because they don't know which parts of the system depend on what. The Refactor workflow reads the investigation's output before touching a single file. Every change is sequenced. Every contract is updated as you go.

Zone 1 — Prerequisites

Coordination Layer

SERVICE CONTRACT.md exists for each in-scope service. Every [INFERRED] field has been validated or explicitly flagged. You know what you're touching.

Dependency Map

DEPENDENCY_MAP.md shows cross-service relationships. Interface mismatches are known. No surprises mid-epic about what breaks what.

Sequenced Plan

Epics are ordered by dependency chain. Low-risk, high-value changes first. No epic touches two load-bearing systems simultaneously.

Zone 2 — The Refactor Loop

The Execution Pattern — read contracts before every change

Five-step workflow for safe, sequenced modernization

Read

Agent reads relevant CONTRACT.md and DEPENDENCY_MAP section before writing any code. Understands what this service promises to consumers.

Implement

Makes the change. Scoped strictly to the epic. Does not improve adjacent code. Does not expand scope.

Validate

Runs tests. Checks that all contract promises are still kept. Verifies nothing downstream is broken.

Update

Updates CONTRACT.md to reflect any changes to the interface, dependencies, or risk profile. Keeps the coordination layer current.

Sync

sync-epic-to-feature · sync-feature-to-plan · update PRODUCT_SOT. The change is now reflected in the living docs layer.

✓ Updated codebase — change is shipped and tested

✓ Updated CONTRACT.md — interface contracts stay current

✓ PRODUCT_SOT.md updated — system state is accurate

✓ Epic archived — with retrospective and feature doc

Zone 3 — Two Refactor Modes

Mode 01 · Solo / Personal

Self-Directed Refactor

1–3 days · One repo · No coordination layer required

You investigated your own project (Self-Audit). You have a CONTRACT.md and a prioritized list of improvements. You work the list top-to-bottom. Each epic is scoped to one area. You update the CONTRACT as you go.

Mode 02 · Modernization Engagement

Client Modernization

Weeks–months · Multi-repo · Full coordination layer required

Post-Audit Sprint. Full DEPENDENCY_MAP and SYSTEM_ARCH in hand. Epics are sequenced by the audit plan. Each epic is fixed-price. Client can stop at any point. Coordination layer stays current throughout.

Zone 4 — What Makes Refactor Different

Contracts First

Every change is preceded by reading the contract. Not the code. The interface promise. This is what prevents the "I thought this was safe to change" failure mode.

Scope Discipline

The epic says what changes. Nothing else changes. No opportunistic improvements. No scope creep. Adjacent debt gets a signal, not a fix.

Living Documentation

The coordination layer is updated with every merged epic. Not at the end of the engagement. Not in a documentation sprint. As you go.