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.