cs-refactor

scan (generate optimization point checklist) → design (confirm which items to implement and the order with the user) → apply (execute item by item, with manual approval for each step)

Fastforward Mode (use for small refactors)

cs-refactor-ff

• Changes span > 1 file
• Expected modification points exceed 3
• Requires visual verification (frontend effects, performance perception)
• Modifies public interfaces (needs to use Parallel Change)
• No test coverage
• Cross-module

Where to place files

codestable/refactors/

codestable/
└── refactors/
    └── {YYYY-MM-DD}-{slug}/
        ├── {slug}-scan.md              ← Optimization point checklist generated in Stage 1
        ├── {slug}-refactor-design.md   ← Execution plan from Stage 2 (selected items, order, verification)
        ├── {slug}-checklist.yaml       ← Generated in Stage 2, used to advance Stage 3
        └── {slug}-apply-notes.md       ← Execution records from Stage 3 (what was done in each step, verification results, deviations)

YYYY-MM-DD-{english slug}

user-form-split

export-perf

Three Stages

Stage 1: scan (Generate optimization point checklist)

First run pre-checks (7 items), stop if any are hit

reference/refusal-routing.md

Lock scan scope

• User specifies specific files/components → scan only those
• User says "this page" → scan the page's entry component + directly imported internal modules, do not trace public dependencies
• User says "this module" → scan files in the module directory, do not go beyond module boundaries
• Scope > 15 files or > 3000 lines → trigger the 6th pre-check, ask the user to narrow the scope

What to look for during scanning

• L1 Behavioral Equivalence Migration Signals: A function is called in many places but its interface/implementation needs modification → candidate for Parallel Change; a whole block of old logic needs to be replaced with a new implementation → candidate for Strangler Fig
• L2 Code-level Refactoring Signals: Overly long functions (> 50 lines / cyclomatic complexity > 10), repeated conditional fragments, mysterious temporary variables, deeply nested if-else
• L3 Structure Splitting Signals: Components > 300 lines, one file handles multiple tasks, container/presentation logic mixed, identical logic written separately in multiple components (frontend); Controller directly calls DB, missing Service layer, Repository bypassed (backend)
• L4 Performance Signals: Repeated calculations (memoizable), N+1 queries, list without virtualization/pagination, event listeners not cleaned up, deep reactivity for large objects (Vue)

reference/methods.md

Output format

{slug}-scan.md

1. Top Overview (one paragraph): Scan scope / number of findings / distribution by category / distribution by risk / recommended priority items / recommended cautious items
2. Checklist Items (one markdown block per item): Field order and hard constraints are in

   reference/scan-checklist-format.md

   in the same directory

{slug}-scan.md

Stage 2: design (Finalize execution plan)

Input

• {slug}-scan.md

  with user selections (✓ items are to be implemented this time, ✗ items are archived for traceability)
• Method library

  reference/methods.md

  (each selected item must map to a method ID M-Ln-NN)

Tasks

1. Sort order. Items with dependencies are placed first (e.g., L1 Parallel Change often needs to run first, followed by L2 extraction). Independent items are prioritized by "low risk + AI self-verifiable", and HUMAN verification items are grouped at the end.
2. Add execution details for each item: Referenced method ID, specific steps, preconditions, exit signals, verification responsible party (AI / HUMAN), rollback strategy (how to restore if problems occur).
3. Identify pre-dependencies: Items with insufficient test coverage need a pre-step of "supplement characterization tests"; items modifying public interfaces need a pre-step of "search for callers".
4. Overall review: Submit the full draft of

   {slug}-refactor-design.md

   to the user. After user approval, change the

   status

   in the frontmatter to

   approved

   .
5. Extract checklist: Extract

   {slug}-checklist.yaml

   from the design, with steps corresponding to execution order and checks corresponding to exit signals for each step.

Design file structure

---
doc_type: refactor-design
refactor: {YYYY-MM-DD}-{slug}
status: draft | approved
scope: {one sentence describing scan scope}
summary: {one sentence describing the items to be implemented}
---

# {slug} refactor design

## 1. Scope of this refactor
- Which items were selected from the scan (listed by number)
- Items explicitly not implemented (marked ✗) and reasons
- Estimated total workload / total risk level

## 2. Pre-dependencies
- Test coverage supplement actions (if needed)
- Caller search actions (if needed)
- Other one-time preparations

## 3. Execution order
List by step, one block per step:
- Step N: {one sentence action}
- Referenced method: M-Ln-NN {method name}
- Specific operations: {apply method library steps to specific files/functions in this project}
- Exit signals: {tests AI runs / pages HUMAN checks}
- Verification responsibility: AI self-verification ｜ HUMAN
- Rollback: {how to restore if problems occur, usually git revert the step}

## 4. Risks and key points
- Summary of high-risk steps (separately highlight steps with high risk in this design)
- Error-prone points (e.g., cross-step data flow changes)

Stage 3: apply (Execute item by item)

Advancement rules

1. One step at a time, no batch operations. Strictly follow the checklist order; do not start the next step until the current step is completed.
2. Verify after each step:
   • AI self-verification items: Run specified tests / type checks / lint / grep for no residual old references. Record in apply-notes if passed, then proceed to the next step.
   • HUMAN verification items: Pause, report "Step N has been completed, please visually confirm at {specific page / operation steps}, I will continue after confirmation". Do not proceed without explicit "continue" from the user.
3. Record deviations immediately: If unconsidered situations are found during execution (e.g., a caller in dynamic import), pause and report, do not act on your own. Align with the user, add the deviation to apply-notes, and return to Stage 2 to modify the design if necessary.
4. Self-check for behavioral equivalence: After each step, ask yourself — "Could this step change externally observable behavior?". If in doubt, roll back the step and do not proceed.

apply-notes format

---
doc_type: refactor-apply-notes
refactor: {YYYY-MM-DD}-{slug}
---

# {slug} apply notes

## Step 1: {action}
- Completion time: {date}
- Modified files: {file list}
- Verification result: {test output / HUMAN confirmation quote}
- Deviations: {none / specific description}

## Step 2: ...

After completion

• Run full tests + type checks + lint
• Ask the user for a final overall visual confirmation (especially for frontend: open key pages and test functions)
• After confirmation, finalize the commit, with the commit message referencing the refactor directory

Exit conditions

• Scan pre-checks have been run; if any were hit, the user was guided to the correct route, and only non-hit cases entered scan
• User has selected items (✓/✗) in

  {slug}-scan.md

  ; unselected items did not enter design
• Each selected item in

  {slug}-refactor-design.md

  is mapped to a method ID in the method library
• Design has passed user overall review, status=approved

• {slug}-checklist.yaml

  has been generated and validated via validate-yaml.py
• Each step in the apply stage has verification records (AI self-verification logs attached, HUMAN confirmation quotes attached)
• Full tests / type checks / lint have passed
• User has passed the final visual confirmation

Common pitfalls

• AI forces checklist entries: Clearly hits pre-checks but finds excuses to bypass, and generates entries with non-quantifiable issues like "code can be more elegant" — should pause immediately and provide routing suggestions
• Includes behavior changes: "Incidentally fixed a bug / optimized a prompt" during refactoring — should pause and split into an independent issue or feature
• Combines cross-step actions: Submits 2-3 steps in one commit for speed — loses the ability to roll back a single step if problems occur
• Includes preference items: Naming preferences, quotes, arrow functions vs function — these go to decisions, not refactor
• Directly starts scanning a large module: Enters scan without splitting a scope of >15 files / >3000 lines, resulting in an unmanageable long checklist
• Skips HUMAN verification items: Frontend effects cannot be seen by AI; cannot replace manual visual inspection with "type checks passed"
• Proceeds with insufficient coverage: Modifies modules without tests, with "behavioral equivalence" only a verbal promise

Boundaries with adjacent workflows

• feature: Adding new capabilities / modifying requirements → feature. If "incidentally implement X" comes up during refactoring, pause and split it out.
• issue: Fixing bugs / correcting behavior → issue. Bugs found during refactoring should be recorded as new issues, not secretly fixed in the current PR.
• decisions: Project-wide long-term constraints ("use composable from now on", "disable mixin") → decisions. Refactor can reference existing decisions as basis, but does not produce decisions.
• architecture: Cross-module boundary restructuring / layer adjustment → architecture + decisions. A single refactor does not cross modules; cross-module work should be split into "update architecture documentation + record decisions + N module-level refactors".
• tricks / learning: Reusable techniques found during refactoring → tricks; pitfalls encountered → learning.

Related documents

• codestable/reference/system-overview.md

  — CodeStable system overview

• cs-refactor-ff/SKILL.md

  — Ultra-light channel for small refactors

• reference/scan-checklist-format.md

  — Fields, order, hard constraints, and anti-pattern samples for scan checklist items

• reference/refusal-routing.md

  — 7 scan pre-checks + routing table + rejection output format

• reference/methods.md

  — Refactor method library (four-layer classification L1-L4, unified fields)

• codestable/reference/shared-conventions.md

  — Shared conventions across workflows
• Project architecture entry — Review before scanning to confirm module boundaries