Execute-Refactor 150 Protocol

Execute-Refactor 150 Protocol

Overview

Run in three stages:

1. Research refactor options (iterative, no code changes).
2. Plan + confirm + implement with tests and validation.
3. Apply Scout105 cleanup (objective, small, user-approved).

Stage 1 — Research refactor options (iterative)

1. Create or reuse the session log at .sessions/​SESSION_[date]-[name].md.

   • If the file does not exist, create it and add the investigation template below.
   • Keep all research notes inside the session log only (no scattered notes in chat).

2. Define the core question (the refactor goal).

   • Write a single sentence: “We need to refactor X to achieve Y.”
   • Example: “Refactor SermonCard to reduce duplication and isolate date logic.”

3. Define scope (Scope150).

   • Core (100%): list files and behaviors you will directly change.
   • Boundary (50%): list callers, dependent modules, tests, configs, and data flow.
   • If unsure, add a “to verify” bullet and resolve it during observations.

4. Perform observations (search/​read) in ordered layers.

   • Interface layer: find entry points (routes, public APIs, UI entry points).
   • Domain layer: identify entities, i18n keys, enums, types.
   • Pattern layer: locate hooks, services, clients, shared utilities.
   • Usage layer: trace imports and call sites.
   • For each layer, read the minimum number of files that explain the behavior.

5. Record findings in the log with sources.

   • Each fact must include a source (file path + line reference or command).
   • Separate facts from hypotheses. Do not mix them.

6. Generate hypotheses and refactor options.

   • For each option, note: goal, steps, benefits, risks, and test impact.
   • Prefer at least 2 options so tradeoffs are explicit.

7. Decide if more research is needed.

   • If user says “research more”, expand scope or inspect new files.
   • Update the log with new branches and continue Stage 1.

8. Stop before implementation.

   • End Stage 1 with: options summary, remaining unknowns, and a recommended path.

Investigation log template

## Investigations

### Investigation: <short topic>

#### Core question
- ...

#### Scope
- Core (100%):
  - ...
- Boundary (50%):
  - ...

#### Findings
- <fact> (source: file path / command)
  - Subfinding

#### Hypotheses
- H1: ...
  - Prediction: ...
  - Test: ...
  - Status: pending/​confirmed/​rejected

#### Refactor options
- Option A: ... (pros/​cons)
- Option B: ... (pros/​cons)

#### Next branches
- ...

Stage 2 — Plan, confirm, implement

1. Write a refactor plan.

   • Break into ordered steps with file-level granularity.
   • Include expected intermediate states (what should still pass after each step).

2. List risks and edge cases.

   • Identify behavior changes, API contract risks, and hidden coupling.
   • Explicitly note any breaking-change risk.

3. Define a validation checklist.

   • Tests to run (unit/​integration).
   • Manual checks if needed (UI flows, API calls).
   • Expected outputs and what would indicate failure.

4. Perform Scope150 validation planning.

   • Core (100%): ensure each planned change has a test or validation step.
   • Boundary (50%): list all callers/​integrations/​tests to be checked.

5. Ask for user confirmation before editing.

   • Provide plan, risks, and validation checklist.
   • Do not edit until the user approves.

6. Implement the refactor.

   • Follow the plan in order.
   • Keep changes minimal and reversible.

7. Add or update tests.

   • Cover changed logic and any new boundaries.
   • Avoid brittle tests; prefer behavior-based assertions.

8. Run validation.

   • Execute all tests from the checklist.
   • Record results and fix failures before moving to Stage 3.

Stage 3 — Scout105 cleanup protocol

Apply only objective cleanup after a Key Point (phase complete). Do not add features.

Trigger (Key Point)

• Apply only after a milestone where the user would see complete value.
• Do not run per-file; run once per phase.

Allowed cleanup categories (objective only)

• Unused code: unused imports/​vars/​fields (provable by grep/​IDE).
• Typos: spelling errors in comments/​strings (spellcheckable).
• Formatting inconsistencies: breaks the file’s own pattern.
• Dead code: commented debug lines or unreachable code.
• Obviously wrong logic: provably incorrect (duplicate checks, impossible types).

Constraints

• Only in files already touched by the primary task.
• Remove garbage only; no new features or refactors.
• Each cleanup must take ≤ 30 seconds to verify + fix.
• Total cleanup time ≤ 5% of primary task time.
• Must be objectively measurable; if not measurable, skip.
• Require user approval before executing cleanup.

Scout105 report (present to user)

✅ Key Point complete: <brief summary>

Scout105 opportunities:
- <file>: <item> (category, evidence)
- <file>: <item> (category, evidence)

Run Scout105 cleanup? [Yes / Skip / Selective]

Execution

• If approved, apply all selected cleanups in batch.
• Run tests/​build to validate no regression.
• If failures occur, revert or investigate causality before proceeding.

Output expectations

• Stage 1: Provide refactor options + log path + remaining branches + recommended path.
• Stage 2: Provide plan, risks, validation checklist, and request confirmation.
• Stage 3: Provide Scout105 report, decision, and validation result.