Structured Refactoring

Phase details live in phases/ — read the relevant file before executing each phase.

Core Principles

Preserve behavior first: never refactor without a passing test suite (exception: testability runs, where the goal is making code testable)
Measure before and after: every change must be justified by metrics
Small incremental changes: commit frequently, never break tests
Save immediately: write artifacts to disk after each phase
Delegate execution: all code changes go through the implement skill via task files
Ask, don't assume: when scope or priorities are unclear, STOP and ask the user

Context Resolution

Announce detected paths and input mode to user before proceeding.

Fixed paths:

Path	Location
PROBLEM_DIR	`_docs/00_problem/`
SOLUTION_DIR	`_docs/01_solution/`
COMPONENTS_DIR	`_docs/02_document/components/`
DOCUMENT_DIR	`_docs/02_document/`
TASKS_DIR	`_docs/02_tasks/`
TASKS_TODO	`_docs/02_tasks/todo/`
REFACTOR_DIR	`_docs/04_refactoring/`
RUN_DIR	`REFACTOR_DIR/NN-[run-name]/`

Prereqs: problem.md required, acceptance_criteria.md warn if absent.

RUN_DIR resolution: on start, scan REFACTOR_DIR for existing NN-* folders. Auto-increment the numeric prefix for the new run. The run name is derived from the invocation context (e.g., 01-testability-refactoring, 02-coupling-refactoring). If invoked with a guided input file, derive the name from the input file name or ask the user.

Create REFACTOR_DIR and RUN_DIR if missing. If a RUN_DIR with the same name already exists, ask user: resume or start fresh?

Input Modes

Mode	Trigger	Discovery source
Automatic	Default, no input file	Skill discovers issues from code analysis
Guided	Input file provided (e.g., `/refactor @list-of-changes.md`)	Reads input file + scans code to form validated change list

Both modes produce RUN_DIR/list-of-changes.md (template: templates/list-of-changes.md). Both modes then convert that file into task files in TASKS_DIR during Phase 2.

Guided mode cleanup: after RUN_DIR/list-of-changes.md is created from the input file, delete the original input file to avoid duplication.

Workflow

Phase	File	Summary	Gate
0	`phases/00-baseline.md`	Collect goals, create RUN_DIR, capture baseline metrics	BLOCKING: user confirms
1	`phases/01-discovery.md`	Document components (scoped for guided mode), produce list-of-changes.md	BLOCKING: user confirms
2	`phases/02-analysis.md`	Research improvements, produce roadmap, create epic, decompose into tasks in TASKS_DIR	BLOCKING: user confirms
		Quick Assessment stops here
3	`phases/03-safety-net.md`	Check existing tests or implement pre-refactoring tests (skip for testability runs)	GATE: all tests pass
4	`phases/04-execution.md`	Delegate task execution to implement skill	GATE: implement completes
4.5	(inline, testability runs only)	Produce `testability_changes_summary.md` listing every applied change in plain language, surface to user	GATE: user acknowledges summary
5	`phases/05-test-sync.md`	Remove obsolete, update broken, add new tests	GATE: all tests pass
6	`phases/06-verification.md`	Run full suite, compare metrics vs baseline	GATE: all pass, no regressions
7	`phases/07-documentation.md`	Update `_docs/` to reflect refactored state	Skip if `_docs/02_document/` absent

Workflow mode detection:

"quick assessment" / "just assess" → phases 0–2
"refactor [specific target]" → skip phase 1 if docs exist
Default → all phases

Testability-run specifics (guided mode invoked by autodev existing-code flow Step 4):

Run name is 01-testability-refactoring.
Phase 3 (Safety Net) is skipped by design — no tests exist yet. Compensating control: the list-of-changes.md gate in Phase 1 must be reviewed and approved by the user before Phase 4 runs.
Scope is MINIMAL and surgical; reject change entries that drift into full refactor territory (see existing-code flow Step 4 for allowed/disallowed lists). Flagged entries go to RUN_DIR/deferred_to_refactor.md for Step 8 (optional full refactor) consideration.
After Phase 4 (Execution) completes, write RUN_DIR/testability_changes_summary.md as Phase 4.5. Format: one bullet per applied change.
```
# Testability Changes Summary ({{run_name}})

Applied {{N}} change(s):

- **{{change_id}}** — changed {{symbol}} in `{{file}}`: {{plain-language reason}}. Risk: {{low|medium|high}}.
```
Group bullets by category (config extraction, DI insertion, singleton wrapping, interface extraction, function split). Present the summary to the user via the Choose format before proceeding to Phase 5.

At the start of execution, create a TodoWrite with all applicable phases.

Artifact Structure

All artifacts are written to RUN_DIR:

baseline_metrics.md                      Phase 0
discovery/components/[##]_[name].md      Phase 1
discovery/solution.md                    Phase 1
discovery/system_flows.md                Phase 1
list-of-changes.md                       Phase 1
analysis/research_findings.md            Phase 2
analysis/refactoring_roadmap.md          Phase 2
test_specs/[##]_[test_name].md           Phase 3
execution_log.md                         Phase 4
testability_changes_summary.md           Phase 4.5 (testability runs only)
test_sync/{obsolete_tests,updated_tests,new_tests}.md  Phase 5
verification_report.md                   Phase 6
doc_update_log.md                        Phase 7
FINAL_report.md                          after all phases

Task files produced during Phase 2 go to TASKS_TODO (not RUN_DIR):

TASKS_TODO/[TRACKER-ID]_refactor_[short_name].md
TASKS_DIR/_dependencies_table.md (appended)

Resumability: match existing artifacts to phases above, resume from next incomplete phase.

Final Report

After all phases complete, write RUN_DIR/FINAL_report.md: mode used (automatic/guided), input mode, phases executed, baseline vs final metrics, changes summary, remaining items, lessons learned.

Escalation Rules

Situation	Action
Unclear scope or ambiguous criteria	ASK user
Tests failing before refactoring	ASK user — fix tests or fix code?
Risk of breaking external contracts	ASK user
Performance vs readability trade-off	ASK user
No test suite or CI exists	WARN user, suggest safety net first
Security vulnerability found	WARN user immediately
Implement skill reports failures	ASK user — review batch reports

7.3 KiB Raw Permalink Blame History Unescape Escape