| name | update-helper |
| version | 5.0.1 |
| description | Safe, high-efficiency code update protocol for AI agents. Use for editing,
patching, debugging, refactoring, porting, or recovering code changes in real
projects, especially when files are large, generated/source files may differ,
UI render and handlers must stay in sync, non-English/BOM text is present,
multiple agents/humans touched the repo, or a previous update broke behavior.
Triggers: "fix this", "add feature", "why is this broken", "remove old UI",
"refactor", "port this", "continue previous agent", "last patch broke it".
Original by PitroyTech. v5.0.1.
|
update-helper v5.0.1
Purpose: update existing code without code blindness. Search first, read bounded ranges, understand enough flow, patch narrowly, verify with syntax/tests and invariants, and keep a clean recovery path.
Respond in the user's language. Keep code identifiers and commands in English. Default is to execute, not explain the protocol, unless the user asks for a plan or review.
Tool Cheat Sheet
| Need | Linux / Claude Code | Windows / PowerShell |
|---|
| Find line by keyword | rg -n "token" file or grep -n | rg -n or Select-String |
| Read bounded range | nl -ba file | sed -n 'N,Mp' | $lines[N..M] via ReadAllLines |
| Replace unique block | str_replace (Claude) / patch tool | apply_patch / .NET Replace |
| Replace all occurrences | sed -i 's/old/new/g' file for simple ASCII only | -replace in .NET content string after encoding check |
| Syntax check JS | node --check file.js | node --check file.js |
| Backup before write | cp file file.bak2 | Copy-Item -LiteralPath |
| Detect encoding | file -bi file; xxd -l 3 file | Read first 3 bytes via ReadAllBytes |
| Search in src+dist | rg -n "token" src dist | rg -n "token" src dist |
| Count brace balance | grep -o '{' f | wc -l | ($c.ToCharArray() | ? {$_ -eq '{'}).Count |
| Rebuild artifact | npm run build / npm run verify | cmd /c npm run build |
Do not use sed -i or blind global replace for Vietnamese/CJK/emoji/BOM-sensitive files. For those, detect encoding first and use explicit encoding-preserving writes.
str_replace / patch failure quick fix:
| Symptom | Cause | Fix |
|---|
| "string not found" | Whitespace / indent mismatch | Re-read exact range, copy verbatim |
| "string not found" | Line numbers shifted after earlier patch | Re-run search to get new coordinates |
| "string not found" | Included line-number prefix from view | Strip the N: or N\t prefix — display only |
| "appears more than once" | Pattern too short | Add 2–3 surrounding lines to make unique |
| "appears more than once" | Want all simple ASCII occurrences | Use a mechanical global replace instead |
Quick Decision
Use Lite Workflow only when all are true:
- Small local change: 1 file, 1-3 functions/blocks.
- Target is obvious and current code matches the request.
- Target file is tracked in git or the edit is a disposable generated artifact.
- No generated/source ambiguity.
- No non-English/BOM/emoji encoding risk.
- No untracked target file.
- No previous failed patch in this session.
- Verification command is clear.
Read and follow the Full Protocol when any are true:
- File is 1,000+ lines or unfamiliar.
- Task touches multiple files/modules.
- User reports runtime/build error.
- Previous patch broke something.
- File contains Vietnamese/CJK/emoji/BOM-sensitive text.
- Target file is untracked, outside git, or the repo state cannot recover the original.
- Refactor, port, migration, or legacy cleanup.
- User spec may be stale.
- Another agent/human changed files.
- You cannot explain data flow before editing.
Backup Decision Matrix
Create a backup before writing whenever any row matches.
| Case | Required backup |
|---|
| Tracked git file, tiny ASCII patch, clean target | .bak2 optional, but allowed |
| Untracked target file | session backup + .bak2 mandatory |
| Non-git workspace | session backup + .bak2 mandatory |
| File 1,000+ lines or unfamiliar | session backup + .bak2 mandatory |
| Generated output or source/dist pair | source .bak2; generated .bak2 only while rebuilding |
| Unicode/CJK/Vietnamese/emoji/BOM-sensitive file | session backup + .bak2 mandatory, detect encoding first |
| Multi-file UI/config/runtime cascade | .bak2 for every written file; session backup for risky/source files |
| Recovery after failed patch/build/runtime issue | do not write again until .bak2 or session backup exists |
Backup naming:
file.ext.bak2 # short-lived per write
file.ext.bak.codex-session-YYYYMMDD-topic # longer rollback point
Never overwrite another agent's session backup. If a backup path already exists, create a new topic suffix or timestamp suffix.
Lite Workflow
Skip nothing.
- Search anchors with
rg, grep -n, or Select-String.
- Read bounded range around anchors, usually 40-160 lines.
- Identify owner function/module and direct callers.
- Say the intended edit in one sentence before writing.
- Apply the Backup Decision Matrix. If any risk row matches, create required backups before writing.
- Patch narrowly.
- Run syntax/build/test check.
- Re-read edited range or search changed anchors.
- Report changed files, verification, backup state, remaining risk.
Lite hard rules:
- Do not read whole large files.
- Do not trust user-quoted code until current code is verified.
- Do not report done without verification.
- If verification fails, stop normal patching and enter Failure Recovery.
Lite Examples By Step
These examples are intentionally concrete. Use the same pattern on Windows/PowerShell or Linux/Bash/Claude Code. Prefer rg; if unavailable, use grep -n or Select-String.
1. Search anchors
Use exact symbols from the bug, not broad words.
Windows:
rg -n "providerModelPool|modelPool|RaceResults|buildPriorityZoneOptions|renderModelPoolUI" src
rg -n "updateLastActiveTimestamp|Structured failed|translateStructured|apply.*translation" src dist
rg -n "batch-gemini|batch-zhipu|api-advanced|geminiBatchInput|zhipuBatchInput" src dist
Linux:
rg -n "providerModelPool|modelPool|RaceResults|buildPriorityZoneOptions|renderModelPoolUI" src
rg -n "updateLastActiveTimestamp|Structured failed|translateStructured|apply.*translation" src dist
rg -n "batch-gemini|batch-zhipu|api-advanced|geminiBatchInput|zhipuBatchInput" src dist
Good cases:
- Dropdown loses Groq after Gemini RACE -> search model pool, provider pool, dropdown render.
- Prompt/response exists but apply fails -> search exact runtime error and apply path.
- Remove old batch/warmup UI -> search old DOM ids, config keys, handlers, status text.
2. Read bounded range
Read only the range around the anchor. Do not read a whole large file.
Windows:
$path = "src/dich_taobao/07-floating-ui-settings.js"
$lines = [System.IO.File]::ReadAllLines($path, [System.Text.Encoding]::UTF8)
for ($i = 3200; $i -le 3330; $i++) { '{0,5}: {1}' -f $i, $lines[$i-1] }
Linux:
nl -ba src/dich_taobao/07-floating-ui-settings.js | sed -n '3200,3330p'
For runtime translation failures:
$path = "src/dich_taobao/priority-zone-engine.js"
$lines = [System.IO.File]::ReadAllLines($path, [System.Text.Encoding]::UTF8)
for ($i = 11800; $i -le 12380; $i++) { '{0,5}: {1}' -f $i, $lines[$i-1] }
nl -ba src/dich_taobao/priority-zone-engine.js | sed -n '11800,12380p'
3. Identify owner function/module and direct callers
Map writer -> store -> reader -> UI/runtime consumer before patching.
Windows:
rg -n "function .*Pool|const .*Pool|setProviderPool|syncModelPoolFromProviderStore|getActivePool" src/dich_taobao
rg -n "buildPriorityZoneOptions|chat-popup-model|priority-zone-engine" src/dich_taobao
rg -n "07-floating-ui-settings|priority-zone-engine|dich_taobao.user" scripts src dist
Linux:
rg -n "function .*Pool|const .*Pool|setProviderPool|syncModelPoolFromProviderStore|getActivePool" src/dich_taobao
rg -n "buildPriorityZoneOptions|chat-popup-model|priority-zone-engine" src/dich_taobao
rg -n "07-floating-ui-settings|priority-zone-engine|dich_taobao.user" scripts src dist
Expected map examples:
RACE -> providerModelPool[provider] -> sync flat modelPool -> dropdown options -> scheduler
TRANSLATE response -> parse JSON -> apply translation -> update UI/cache/logs
Settings render -> DOM id -> event binding -> config save/default/reset
4. Say intended edit before writing
Write one sentence to the user or your scratchpad. This prevents blind edits.
Good:
I will make providerModelPool the source of truth, refresh modelPool from all providers after each RACE, and keep dropdown rendering from the aggregate list.
Good:
I will remove the old Batch tuning control across render, CSS, event binding, config defaults, and stale status text, then verify old ids have no active hits.
Bad:
I will tweak the dropdown.
5. Backup before writing
For Lite, backup is optional only when the patch is truly tiny, the target is tracked in git, and git can recover the original. Otherwise follow the Backup Decision Matrix.
Before backup, check whether the target is tracked:
git ls-files --error-unmatch "file.ext"
git status --short -- "file.ext"
git ls-files --error-unmatch file.ext
git status --short -- file.ext
Create .bak2 before every risky write:
Windows:
Copy-Item -LiteralPath "src/dich_taobao/07-floating-ui-settings.js" -Destination "src/dich_taobao/07-floating-ui-settings.js.bak2" -Force
Linux:
cp src/dich_taobao/07-floating-ui-settings.js src/dich_taobao/07-floating-ui-settings.js.bak2
If there is no git, also keep a session backup:
Copy-Item -LiteralPath "file.ext" -Destination "file.ext.bak.codex-session-YYYYMMDD-topic" -Force
cp file.ext "file.ext.bak.codex-session-$(date +%Y%m%d)-topic"
If the target is untracked in an otherwise git workspace, treat it like non-git for that file: create the session backup and report it.
6. Patch narrowly
Patch the owner block, not every nearby string. For normal repo edits, use the patch tool. For encoding-sensitive full-file rewrites, preserve BOM/no-BOM exactly.
Windows encoding check before risky rewrite:
$path = "src/dich_taobao/07-floating-ui-settings.js"
$b = [System.IO.File]::ReadAllBytes($path)
if ($b.Length -ge 3 -and $b[0] -eq 0xEF -and $b[1] -eq 0xBB -and $b[2] -eq 0xBF) { "UTF-8 BOM" }
elseif ($b.Length -ge 2 -and $b[0] -eq 0xFF -and $b[1] -eq 0xFE) { "UTF-16 LE" }
else { "UTF-8 no BOM or ASCII" }
Linux encoding check:
file -bi src/dich_taobao/07-floating-ui-settings.js
xxd -l 3 src/dich_taobao/07-floating-ui-settings.js
Patch examples:
- Dropdown bug: patch provider pool writer and dropdown hydration, not only option labels.
- Runtime error after response: patch missing function/call path after response parsing, not API keys.
- UI removal: patch render + handler + config + status text together.
7. Run syntax/build/test check
Prefer the project verification command when known. On JS repos, cmd /c npm run verify is often safer in PowerShell than plain npx.
Windows:
node --check src/dich_taobao/07-floating-ui-settings.js
node --check dist/dich_taobao.user.js
cmd /c npm run verify
Linux:
node --check src/dich_taobao/07-floating-ui-settings.js
node --check dist/dich_taobao.user.js
npm run verify
Other language quick checks:
python3 -m py_compile file.py
go test ./...
cargo check
php -l file.php
ruby -c file.rb
bash -n script.sh
8. Re-read edited range or search changed anchors
Prove the intended change exists and stale behavior is gone.
Windows:
rg -n "providerModelPool|setProviderPool|syncModelPoolFromProviderStore" src/dich_taobao dist/dich_taobao.user.js
rg -n "clearPoolByProvider\('gemini'\)|clearPoolByProvider\('groq'\)|config\.modelPool = \[" src/dich_taobao
rg -n "batch-gemini|batch-zhipu|api-advanced|geminiBatchInput|zhipuBatchInput" src dist
Linux:
rg -n "providerModelPool|setProviderPool|syncModelPoolFromProviderStore" src/dich_taobao dist/dich_taobao.user.js
rg -n "clearPoolByProvider\('gemini'\)|clearPoolByProvider\('groq'\)|config\.modelPool = \[" src/dich_taobao
rg -n "batch-gemini|batch-zhipu|api-advanced|geminiBatchInput|zhipuBatchInput" src dist
Interpretation:
- New owner symbols should exist in source and generated output if generated output is used.
- Removed UI ids/functions should have zero active hits or only documented migration notes.
- If a model returned JSON, failures after that point are runtime/apply failures, not key failures.
9. Report changed files, verification, backup state, risk
Keep final report short and concrete.
Changed : src/dich_taobao/07-floating-ui-settings.js, dist/dich_taobao.user.js
Behavior : provider RACE now updates providerModelPool and dropdown hydrates from aggregate store.
Verification : npm run verify -> OK; invariant search found no old shared-pool overwrite path.
Backup state : .bak2 deleted after pass; session backup kept at file.ext.bak.codex-session-YYYYMMDD-topic.
Remaining risk: browser click-test recommended for settings dropdown.
Pre-Submit Checklist
Run before marking any patch done. Skip only items that provably don't apply.
[ ] Session backup exists for risky, non-git, generated, or encoding-sensitive modified files
[ ] .bak2 created before this write (or target is tracked, tiny, ASCII, and git can recover trivially)
[ ] Untracked targets have a session backup before the first write
[ ] Backup paths do not overwrite another agent's backup
[ ] old_str / patch anchor copied from actual file, not user-quoted spec
[ ] Anchor is unique in file (or context added until unique)
[ ] Encoding verified for non-ASCII files; BOM/no-BOM preserved after write
[ ] Re-read edited range — intended change is visible in file
[ ] Syntax/build check passed
[ ] .bak2 deleted after pass (or kept if failed)
[ ] If backup files are accumulating, suggest cleanup only after test/check passes and user confirms behavior
[ ] Invariant search: old ids/functions -> 0 hits (or documented exception)
[ ] Cascade check: all callers, consumers, generated output updated
[ ] Report includes: changed files, behavior, verification, backup state, remaining risk
FULL PROTOCOL BOUNDARY
Everything below is the full protocol. Use it for risky, unclear, multi-file, generated-file, encoding-sensitive, refactor/port, UI, or recovery work.
0. Hard Rules
- Search before reading. Read bounded ranges, not whole large files.
- Before writing: identify source-of-truth files versus generated outputs/reference files.
- Detect encoding and create a session backup before the first risky write.
- Create/refresh
.bak2 immediately before each risky write.
- Preserve encoding exactly: UTF-8 BOM stays BOM, UTF-8 no-BOM stays no-BOM.
- Use stable ASCII anchors when terminal output may show mojibake.
- Patch render + handler + state + save/config + CSS together when UI controls change.
- Run syntax/build/tests and invariant searches after meaningful edits.
- Delete
.bak2 only after verification passes. Clean session backups only under Backup Cleanup Protocol.
- Never revert unrelated user/human/agent changes.
1. Source-of-Truth Detection
Before patching, determine which file actually controls runtime.
Search build scripts and generated hints with rg "build|dist|bundle|generated|do not edit" package.json scripts src ., then classify files:
SOURCE : files humans should edit
GENERATED : build output; regenerate after source edits
REFERENCE : old monolith/spec/sample; do not patch unless requested
UNKNOWN : inspect build path before writing
Do not patch generated output as the only fix unless the user explicitly wants a one-off artifact edit. If user-run artifact is generated, patch source then rebuild output.
Example:
src/dich_taobao/07-floating-ui-settings.js SOURCE
src/dich_taobao.user.js REFERENCE/stale monolith
dist/dich_taobao.user.js GENERATED user artifact
2. Search And Bounded Read
rg -n "renderApiProviderCard|batch-gemini|api-advanced" src/
grep -n "uniqueToken\|rareFunction" file.js
Select-String -LiteralPath "file.js" -Pattern "uniqueToken|rareFunction" | Select-Object LineNumber, Line
$lines = [System.IO.File]::ReadAllLines("file.js", [System.Text.Encoding]::UTF8)
for ($i = 1200; $i -le 1280; $i++) { '{0,6}: {1}' -f $i, $lines[$i-1] }
If the requested anchor is not found anywhere, stop and ask. The code may have been refactored.
3. Architecture And Flow Map
Before non-trivial edits, produce a compact map for yourself and, when helpful, share it.
Structural scan:
rg -n "^function |^const |^class |^async function |^export " file.js
rg -n "addEventListener|\.onclick|\.on\(|saveConfig|render" file.js
rg -n "targetSymbol" src/
Select-String -LiteralPath "file.js" -Pattern "^function |^const |^class |^async function |^export " | Select-Object LineNumber, Line
Select-String -LiteralPath "file.js" -Pattern "addEventListener|\.onclick|saveConfig|render" | Select-Object LineNumber, Line
Map format:
ARCHITECTURE_MAP:
source-of-truth : src/module.js -> dist/app.js generated by npm run build
config/state : config.apiKeys, config.modelPool
render : renderSettings()
handlers : bindSettingsEvents(), saveConfig()
flow : UI input -> state -> API call -> cache/render
blast radius : dropdown IDs, event handlers, scheduler consumers
Blast-radius questions:
- Direct: what code changes?
- Indirect: who calls/consumes it?
- State: what shared config/global fields are read/written?
- UI: what DOM IDs/classes/events are affected?
- Timing: async callbacks/debounce/race?
- Build: what output must be regenerated?
4. Safe Edit Protocol
Encoding detection: inspect first bytes for UTF-8 BOM / UTF-16 LE / UTF-8 no BOM before risky rewrites. Session backup, once per target/work stream:
BAK="file.ext.bak.session-$(date +%Y%m%d)-topic"
[ ! -f "$BAK" ] && cp file.ext "$BAK"
$sessionBak = "file.ext.bak.codex-session-YYYYMMDD-topic"
if (-not (Test-Path -LiteralPath $sessionBak)) {
Copy-Item -LiteralPath "file.ext" -Destination $sessionBak -Force
}
Pre-write backup:
cp file.ext file.ext.bak2
Copy-Item -LiteralPath "file.ext" -Destination "file.ext.bak2" -Force
Before editing an untracked file, confirm and back it up:
git status --short -- "file.ext"
$sessionBak = "file.ext.bak.codex-session-YYYYMMDD-topic"
Copy-Item -LiteralPath "file.ext" -Destination $sessionBak -Force
Copy-Item -LiteralPath "file.ext" -Destination "file.ext.bak2" -Force
git status --short -- file.ext
cp file.ext "file.ext.bak.codex-session-$(date +%Y%m%d)-topic"
cp file.ext file.ext.bak2
After success:
rm file.ext.bak2
Remove-Item -LiteralPath "file.ext.bak2" -Force
Backup Cleanup Protocol
Goal: keep rollback while editing, then remove backup noise only when it is safe.
Always:
- Keep
.bak2 while the current write is unverified.
- Delete
.bak2 only after syntax/build/tests and invariant searches pass.
- If verification fails, restore
.bak2, re-read the exact range, patch smaller, verify again.
- Never delete the only known-good copy in a non-git workspace.
- Never delete the only known-good copy of an untracked file in a git workspace.
Git workspace cleanup:
git status --short
git diff -- file.ext
npm run verify
rm file.ext.bak2
git status --short
git diff -- "file.ext"
cmd /c npm run verify
Remove-Item -LiteralPath "file.ext.bak2" -Force
Session backup cleanup is allowed only when all are true:
git status --short shows the intended changed files and no surprise target-file changes.- Every edited target is tracked, or the user explicitly allowed cleanup of untracked-file backups.
git diff -- file.ext is readable and contains the intended patch.- Verification passed.
- The final answer reports changed files and backup state.
Then either keep the session backup for the user to delete later, or delete it if the user asked for a clean workspace:
rm "file.ext.bak.codex-session-YYYYMMDD-topic"
Remove-Item -LiteralPath "file.ext.bak.codex-session-YYYYMMDD-topic" -Force
Non-git workspace cleanup:
sha256sum "file.ext.bak.codex-session-YYYYMMDD-topic" file.ext
npm run verify
rm file.ext.bak2
Get-FileHash -Algorithm SHA256 "file.ext.bak.codex-session-YYYYMMDD-topic"
Get-FileHash -Algorithm SHA256 "file.ext"
cmd /c npm run verify
Remove-Item -LiteralPath "file.ext.bak2" -Force
Keep the session backup by default in non-git workspaces. Delete it only when the user explicitly asks for cleanup or you created a newer verified archival backup. In the final answer, tell the user where the session backup is.
Keep the session backup by default for untracked source/reference files too, even inside a git repo. Git cannot restore those originals.
Backup Cleanup Suggestion
If multiple .bak, .bak2, or *.bak.codex-session-* files accumulate after a few sessions, do not silently delete them. Suggest cleanup to the user with a short list of candidates and the safety gate:
I see several backup files from previous sessions. After verify/check passes and you confirm the current behavior is good, I can clean the old backups.
Only clean backup files when all are true:
- Current source/build/test or project verify command has passed.
- The user has tested or explicitly confirmed the current behavior is good enough to keep.
- The candidate backup files are clearly backup artifacts, not source/reference files.
- No backup is the only known-good copy for an untracked or non-git file.
- The cleanup command targets explicit filenames or a reviewed candidate list, not a broad wildcard.
Default stance: keep backups during active debugging; offer cleanup at handoff or after the user reports the feature is stable.
Generated files:
- If source was patched and generated output rebuilt, delete
.bak2 for both only after source verification and generated artifact verification pass.
- Do not keep backup artifacts inside
dist/ longer than the current turn unless the user asks; generated files can usually be rebuilt.
Tool selection: use normal patch tools for small code edits; use explicit Python/.NET encoding writes for full-file or Unicode-sensitive rewrites; patch source then rebuild generated artifacts. Windows encoding-safe rewrite:
$path = "C:\path\file.ext"
$b = [System.IO.File]::ReadAllBytes($path)
$hasBom = $b.Length -ge 3 -and $b[0] -eq 0xEF -and $b[1] -eq 0xBB -and $b[2] -eq 0xBF
$content = [System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8)
$nl = if ($content.Contains("`r`n")) { "`r`n" } else { "`n" }
# Modify content using stable ASCII anchors. Avoid terminal-rendered mojibake text.
$utf8 = [System.Text.UTF8Encoding]::new($hasBom)
[System.IO.File]::WriteAllText($path, $content, $utf8)
Forbidden for encoding-sensitive files:
Get-Content | Set-Content
Set-Content -Encoding UTF8
WriteAllLines after Get-Content
copying terminal mojibake into source
5. UI Removal And Settings Changes
When adding/removing/changing a UI control, patch all matching paths.
Checklist:
Render/HTML : element, id, class, label
CSS : selectors and layout rules
Event binding : querySelector, onclick, addEventListener
State/config : save path, defaults, migration, reset buttons
Status/logging : user feedback and debug output
Consumers : scheduler/API/cache/dropdowns using that state
Generated output : rebuild dist if needed
Invariant search : old id/class/function should be zero unless intentionally kept
Removal invariant example:
rg -n "batch-gemini|batch-zhipu|api-advanced|geminiBatchInput|zhipuBatchInput" src dist
If a removed DOM id still appears in active code, the task is not done.
For dynamic API/model settings:
- Keep raw API model IDs separate from friendly display names.
- Do not show key labels A/B/C as the primary model identity unless the user needs key debugging.
- Live provider IDs are for API calls; labels are for UI only.
- If a provider is removed from active registry, check settings UI, scheduler, planner dropdowns, model pool, and cache keys.
- After RACE/test/reload buttons, status should say what happened, not just change the button text.
6. Refactor And Port Protocol
Use for behavior-preserving restructure, cross-module changes, or moving a feature between projects.
Pre-work:
rg -n "oldFunction|oldPattern" src/
rg -n "functionBeingChanged" src/
rg -n "import .*module|require\(" src/
Build a map before editing:
REFACTOR_MAP:
source behavior : what currently works
target behavior : what must remain/change
dependencies : imports, globals, config keys, env vars, CSS classes
call order : leaf -> callers -> entry point
verification : syntax, tests, invariant searches
Execution order:
Correct: leaf function -> direct caller -> parent flow -> entry point
Wrong : entry point first, then chase breakage
For ports:
- List dependencies in source project.
- Map each dependency to target project equivalent.
- Identify missing helpers/config/styles.
- Patch target in small slices.
- Verify target behavior, not just compile success.
7. Stale Spec Handling
User specs and previous-agent notes can be stale.
If spec differs from current code:
Spec says : old shape
Current code : actual shape
Difference : what changed
Recommendation : adapt / apply as-is / skip
Ask if applying stale spec could destroy current behavior. If the safe adaptation is obvious and local, adapt and mention it. If not obvious, stop and ask.
Never silently merge stale instructions into unfamiliar code.
8. Failure Recovery
Rollback decision tree:
Syntax error just introduced
-> restore .bak2 -> re-read exact range -> smaller patch -> verify
Build/test fails after patch
-> keep backups -> do not patch randomly -> trace failure to changed symbol -> targeted fix -> verify
Runtime wrong behavior, no error
-> ensure session backup exists -> backward trace from bad output -> state mutation -> handler/render path -> targeted fix
Encoding/mojibake corruption
-> stop -> restore .bak2/session backup -> detect encoding -> rewrite with explicit encoding
Multiple files broken
-> list broken files -> restore each from its own backup -> redo blast radius before patching
No backup exists for risky/untracked target
-> stop edits -> create backup from current file -> decide whether current file is already damaged -> ask if original cannot be reconstructed
Rules:
- Do not add a second workaround on top of a broken first patch.
- Re-read after restore.
- If the same patch fails twice, stop and ask.
- If a required backup was skipped, say so plainly in the final report and keep any new recovery backup created afterward.
9. Verification
Syntax/build checks: JS node --check, TS npx tsc --noEmit, Python python3 -m py_compile, Go go test ./..., Rust cargo check, PHP php -l, Ruby ruby -c, Bash bash -n, PowerShell parser. Project verification beats generic syntax check when available:
npm run verify
npm test
npm run build
Post-patch invariants:
rg -n "oldId|oldFunction|oldConfigKey" src dist
rg -n "newId|newFunction|newConfigKey" src dist
Cascade checks:
| Change | Verify |
|---|
| Rename function | All call sites |
| Change signature | All callers pass correct args |
| Change return shape | All consumers parse new shape |
| Remove DOM id/class | Render, CSS, handlers, tests, dist |
| Change config key | Defaults, migration, readers/writers |
| Change provider/model | UI dropdowns, API calls, scheduler, cache |
| Generated output | Build regenerated artifact |
10. Multi-Agent Handoff
When joining an in-progress session, run these steps before patching:
- Verify session backup exists for every risky or untracked target. Create immediately if missing.
- Check for ARCHITECTURE_MAP or notes from previous agent. If found, read before touching code. If not, run Section 3 Structural Scan.
- Check for feature_map / knowledge index files:
find . -maxdepth 3 \( -iname "*feature_map*" -o -iname "*KI*" -o -iname "*knowledge*" \) 2>/dev/null
Get-ChildItem -Recurse | Where-Object { $_.Name -match 'feature_map|knowledge|KI' } | Select-Object FullName
If found, read before writing any code.
- Confirm tool availability:
node, python3, go, npm run verify as needed.
- Check git status for changes by other agents/humans:
git status --short. Re-verify anchors if target files are dirty.
Rules:
- Do not overwrite another agent's session backup.
- If a human changed a file, re-check anchors before applying pending patches.
- Treat previous notes as hints, not truth. Verify against live code.
- If worktree is dirty, do not revert unrelated changes.
- If target files are untracked, git cannot recover them. Create session backups before the first write and keep them through final handoff.
11. Example Scenarios
A. Remove old settings control safely
Task: remove Batch tuning from API settings.
Correct flow:
Search: batch-gemini, batch-zhipu, api-advanced
Read : render block, CSS block, Gemini handler, Zhipu handler, generic provider save
Patch: remove visible controls, remove default buttons, remove save reads, remove null-crash handlers
Verify: npm run verify
Invariant: rg "batch-gemini|batch-zhipu|api-advanced|geminiBatchInput|zhipuBatchInput" src dist -> 0
B. Fix generated/source confusion
Task: userscript does not reflect settings change.
Correct flow:
Find build script -> identify source chunks -> patch source chunk -> run npm run build/verify -> inspect dist -> leave stale reference untouched
C. Recover from mojibake display
Task: patch Vietnamese UI string, terminal displays garbage.
Correct flow:
Do not patch using garbled terminal text.
Use ASCII anchors around the block.
Detect BOM/no-BOM.
Write with explicit encoding.
Verify known string or invariant after write.
D. API provider cleanup
Task: remove provider or weak models.
Correct flow:
Registry -> settings tabs -> planner provider dropdown -> model filters -> scheduler candidates -> cache/model pool -> status logs -> dist build
12. Concise Final Report
Final response should include only high-signal items:
Changed : file.js, dist/app.js
Behavior : removed old Batch UI and dead handlers; moved key visibility toggle beside Add key
Verification : npm run verify -> OK
Invariants : old batch IDs/functions -> 0 hits in source/dist
Backup state : .bak2 deleted after pass; session backup kept/removed per user preference
Remaining risk: browser visual check if UI layout changed
