cs-refactor-ff
When a user says "optimize this function" and the changes are clearly minor (a single function gets longer, extract a composable from a component, merge duplicate code), going through the full three-stage workflow is overkill. fastforward does one thing: let AI modify directly like it normally would, but sticks to the bottom line of refactor - behavioral equivalence, using classic methods, and validating itself by running tests.
So this skill is extremely lightweight. No scan checklist, no design doc, no checklist - just a one-sentence report after modification.
3 Hard Entry Checks (Exit to Full Workflow if Any Fail)
Before starting, ask yourself 3 questions. If any fail, switch back to the
full workflow:
- Is behavior truly unchanged? If the user's description includes "also support X / change to Y" - this is a behavioral change, not a refactor. Ask the user to split it into a feature / issue workflow.
- Is the scope truly small? If changes involve more than 1 file, or over 100 lines in a single file, or more than 3 expected modification points - switch to the full workflow.
- Is there test coverage for self-validation? The target code has tests covering it (unit tests / integration tests / type checks can catch issues) - if no tests exist, switch to the full workflow, or create a characterization test first before returning.
The full scan stage of entry checks has 7 items, which are compressed to the 3 most critical ones here - the remaining 4 items (cross-module, full flavor, generated code, incomplete scan) are already implicitly excluded in "Is the scope truly small?".
Use Classic Methods, No Improvisation
fastforward doesn't read the complete method library, but must adhere to: "Every change must correspond to a classic refactor method". If AI can't identify which classic method (e.g., Extract Function / Memoization / Guard Clauses / ...) a change corresponds to, it means this isn't a simple refactor - switch to the full workflow to check the method library.
Common methods (covering 80% of fastforward scenarios):
- Extract Function: A segment of >5 lines, cohesive, and namable → extract into an independent function
- Extract Variable: Complex expressions → name as variables or queries
- Guard Clauses: Multi-layer nested if checks at the start → return early to flatten the structure
- Decompose Conditional: Complex if conditions → name as boolean functions
- Extract Composable / hook: Encapsulated state + side effects in a component → extract into an independent composable / hook
- Memoization: Repeated calculations → use computed / useMemo
- Cancellation: Missing cleanup for side effects → add onUnmounted / useEffect return
If the intended action isn't among these or isn't an out-of-the-box classic method (e.g., involves Parallel Change / Strangler Fig / layered correction) - switch to the full workflow.
Workflow
1. One-Time Alignment
After receiving the request, reply to the user in one sentence: "I plan to use {method name}, modify {specific file/function}, with {N} modification points, expected impact {scope}. Confirm to start."
Proceed to the next step if the user confirms. If the user says "also need to change X" - evaluate whether this X violates the 3 entry checks. If it does, switch to the full workflow.
2. Modify
Modify according to the steps of the classic method. No design doc or checklist is produced. Code changes are directly committed.
3. Self-Validation
- Run tests (unit / integration / type checks / lint)
- Use grep to check if old references are fully cleaned up (for changes like Extract Function / Inline Function)
- If front-end state logic is modified, run type checks + existing tests; do not perform UI visual verification - UI visual checks should not use fastforward.
4. One-Sentence Report
Format:
✓ Completed. Method: {method name}. Changes: {file path: line number range}. Validation: {tests run / pass status}.
If there are deviations, or if you want to make additional changes during application - stop and ask the user, do not improvise.
File Output
By default,
do not create a directory under - the value of fastforward lies in leaving no archives.
Exception: If the user explicitly says "keep a record of this small refactor" - create a
codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md
, whose content is the above report plus a section "What was done / Why". No design doc or checklist is written.
When to Exit fastforward
If any of the following situations occur during modification, stop and tell the user "It's more complex than expected, suggest switching back to the full refactor workflow":
- Number of modification points increases from 3 to 5+
- Discover that more than 1 file needs to be modified
- An action not in the common method list emerges
- Discover no test coverage for the changes
- User adds "also change X" which introduces behavioral changes
- AI self-validation fails after modification (tests fail) and it can't be fixed with simple corrections
Switchback method: Trigger
, starting from the scan stage. The modified parts can either be committed and retained, or restored to a clean state with
before scanning, depending on the user's decision.
What Not to Do
- Do not write scan checklists / design docs / checklists - writing them defeats the purpose of fastforward
- Do not modify across multiple files - cross-file changes are not "small refactors"
- Do not make changes requiring human visual verification - front-end rendering / interaction / performance perception that requires human review should use the full workflow
- Do not touch public interfaces - modifying public interfaces requires Parallel Change, which cannot be done via fastforward
Common Pitfalls
- Judging "small" too broadly: User says "small refactor" but actually needs to modify 3 files - AI should honestly say "This isn't small, suggest using the full workflow"
- Starting modification without passing the 3 entry checks: The significance of this skill lies in these 3 checks
- Cutting corners on self-validation: Only running type checks instead of unit tests, or not using grep to check old references at all
- Improvising during modification: "Fixing" neighboring code along the way - the scope of fastforward is locked at the time of confirmation, and should not be expanded afterward
- Disguising behavioral changes as refactors: Adding a new parameter, changing return value format - these are behavioral changes and cannot be disguised
Related
- - Full refactor workflow, switch to this for complex cases
cs-refactor/reference/methods.md
codestable/reference/system-overview.md