Required reading before starting
Before making any judgment or action, first execute CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read an external AI entry as a substitute (see .codestable/reference/execution-conventions.md）。
When the user says "optimize this function" and the change is obviously very small (lengthening a single function, extracting a composable from a component, merging a piece of duplicated code), going through the full three phases is too heavy. fastforward lets the AI modify directly as usual but keeps the bottom line—behavior equivalence, citing classic methods, running tests to self-verify.
Very light: no scan checklist, no design doc, no checklist; after the change, a one-sentence report is enough.
Execution gate (worktree + commit)
Run the start gate before changing,{slug} is the refactor directory name:
python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/refactors/YYYY-MM-DD-{slug}
If the gate does not pass, do not touch the code; for an override, first write in the unit directory worktree-override.md(reason / scope / approval). After self-verification passes and before committing, run the commit gate (same command commit); if it does not pass, handle the findings first. For gate installation and the branch-guard hook, see .codestable/reference/branch-guard-hooks.md。
3 hard entry checks (if not passed, fall back to the full process)
If any one fails, fall back to cs-refactor：
- Is the behavior really unchanged? The user's description smuggles in "also support X / change it to Y"—this is a behavior change, not a refactor; have the user split it out and go through feature / issue
- Is the scope really small? More than 1 file / more than 100 lines changed in a single file / more than 3 expected change points—fall back to the full process
- Are there tests that can self-verify? The target code has coverage (unit tests / integration tests / type checking can catch it)—if there are no tests, fall back to the full process, or first create a characterization test and then come back
The full scan phase has 7 entry checks; here they are compressed into the 3 most critical ones—the remaining 4 (cross-module / all flavors / generated code / cannot finish scanning) are already implicitly excluded under "Is the scope really small?".
Use classic methods, no improvisation
fastforward does not read the full method library, but it must uphold "every change can correspond to a classic refactoring method". If the AI cannot think of which one among "this step is Extract Function / Memoization / Guard Clauses / ..." → this is not a simple refactor; fall back to the full process to check the method library.
Common methods (covering 80% of fastforward scenarios):
- Extract Function: > 5 lines, cohesive, nameable fragment → extract into a separate function
- Extract Variable: complex expression → named variable or query
- Guard Clauses: multiple nested if checks at the beginning → early return to flatten
- Decompose Conditional: complex if condition → name it as a boolean function
- Extract Composable / hook: closed state + side effects in a component → separate composable / hook
- Memoization: repeated computation → computed / useMemo
- Cancellation: side effect missing cleanup → add onUnmounted / useEffect return
If the action you want to take is not among these and is not an out-of-the-box classic method (involving Parallel Change / Strangler Fig / layered correction) → fall back to the full process.
Process
1. Align once
Reply to the user in one sentence:"I plan to do {method name}, touching {specific file/function}, with {N} change points, expected impact {scope}. Confirm and I'll start."
If confirmed, go to the next step. If the user says "there is also an X to change"—evaluate whether X breaks the 3 entry checks; if it does, fall back to the full process.
2. Modify
Modify following the classic method steps. Do not produce a design doc / checklist; write code directly to disk.
3. Self-verification
- After completion, first enter
cs-code-reviewfor an independent diff review; do not proceed to commit until Critical/Important are cleared to zero; the right to initiate scoped-commit belongs tocs-code-review - Run tests (unit / integration / type check / lint)
- grep to check whether old references have been cleaned up (if you did something like Extract / Inline)
- If you changed frontend state logic, run type check + existing tests;do not do visual UI verification— if visual UI is needed, fastforward should not be used
4. One-sentence report
✓ 已完成。方法：{方法名}。改动：{文件路径:行号范围}。验证：{跑了什么测试 / 通过情况}。
If there is deviation / during apply you find you want to change something else → stop and ask the user, do not improvise。
File output
DefaultDo not create the .codestable/refactors/ directory— the value of fastforward lies in leaving no archive.
Exception: the user explicitly says "this time I want a record kept" → create .codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md, and the content is just the report sentence above + a section on "what was done / why". Do not write design / checklist.
When to jump out of fastforward
If any of the following appears halfway through the change,stop and tell the user "this is more complex than expected, recommend switching back to the full process"：
- The number of change points grows from 3 to 5+
- You find that more than 1 file needs to be changed
- An action appears that is not in the common method list
- You find there are no tests that can cover it
- The user adds "by the way, change X too", bringing in a behavior change
- After the change, AI self-verification fails and it is not something a simple fix can handle
Switch back: trigger cs-refactor to start from scan. The parts already changed should either be committed and kept, or git restore return to a clean state and then scan.
What not to do
- Do not write scan / design / checklist — writing them violates the reason fastforward exists
- Do not change across multiple files — cross-file is not a "small refactor"
- Do not make changes that require HUMAN visual verification — frontend rendering / interaction / performance perception that people need to look at should go through the full process
- Do not touch public interfaces — changing public interfaces requires Parallel Change, which is not something fastforward can do
Common pitfalls
- Judging "small" too broadly: the user says "small refactor" but it actually touches 3 files — AI must honestly say "this is not small"
- Skipping the 3 entry checks and just starting: the meaning of this skill lies in these 3 checks
- Being lazy in self-verification: only running type check without running unit tests, or not grepping old references at all
- Improvising during the change: seeing neighboring code and "changing it along the way too" — the fastforward scope is locked the moment it is confirmed
- Disguising behavior changes as refactoring: adding new parameters, changing return value formats — this is a behavior change and cannot be disguised
Related
cs-refactor/SKILL.md— full refactor processcs-refactor/reference/methods.md— full method library.codestable/reference/system-overview.md— CodeStable system overview