菜单
When a patch edit corrupts a file (syntax error, mismatched braces, nested function inside wrong scope) — restore from git and re-patch cleanly instead of patching the broken state.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | patch-corruption-recovery |
| description | When a patch edit corrupts a file (syntax error, mismatched braces, nested function inside wrong scope) — restore from git and re-patch cleanly instead of patching the broken state. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| metadata | {"hermes":{"tags":["debugging","patch","git","recovery","troubleshooting"],"related_skills":["systematic-debugging"]}} |
These symptoms mean a patch landed incorrectly and the file is corrupted:
SyntaxError: Unexpected } or Unexpected token after a patchbun run typecheck shows NEW errors in a file that was clean before the patchparsePdf inside fileMimeFromPath)Find the last known-good commit and verify it had no errors:
# Check recent commits
git log --oneline -5
# Restore file to last known good commit (DON'T commit yet)
git checkout <last-good-commit> -- path/to/corrupted/file
# Verify typecheck passes
bun run typecheck
# Should show 0 errors (ignore node_modules pre-existing errors)
# Restore to clean state — this is the cleanest path
git checkout <last-good-commit> -- path/to/corrupted/file
After each patch, verify before proceeding:
# Verify typecheck
bun run typecheck
# Verify startup (for server files)
timeout 5 bun src/index.ts
git add -A && git commit -m "description"
When a patch corrupts a file, the file structure is already wrong:
Trying to fix with more patches is like trying to untangle by adding more knots.
The cleanest path is always:
Corrupted file → git restore to last clean → re-patch correctly
fileMimeFromPath function body got replaced because old_string matched from import pdf-parse to its closing } — the patch tool matched first occurrence which was INSIDE fileMimeFromPath, replacing the entire function body with parsePdf definitiongit checkout 343ec07 -- backend/src/routes/chat.ts then re-apply all patches cleanly| Practice | Why |
|---|---|
| Typecheck BEFORE and AFTER each patch | Catch corruption immediately, not after 3 more patches |
| One concept per patch | If a 50-line file becomes 120 lines after a patch meant to add 20, something went wrong |
Check git diff --stat | Always look at what actually changed |
| Verify startup for server files | timeout 5 bun src/index.ts catches runtime errors typecheck misses |
Re-read the full file with read_file (no offset/limit) before patching a region that has nearby lookalike blocks | Avoids patch fuzzy-match anchoring on the wrong copy of a repeated anchor (see "Adjacent-anchor pitfall" below) |
| Pause on "Found 2 matches for old_string" errors | It means the file has near-duplicate anchor regions (e.g. two consecutive import { ... } blocks). Add MORE surrounding context, don't blindly replace_all |
Symptom: patch replace silently deletes a comment block 5 lines
above the intended anchor, while the actual edit lands correctly.
Typecheck / build passes because the deleted lines were a comment —
so the corruption is INVISIBLE until someone reads the file.
Root cause: I had used read_file(..., offset=15, limit=20) to
inspect a region of ChartBlock.tsx. The first 20 lines contained
one occurrence of a 5-line "Register the controllers..." comment.
A few lines below, the actual ChartJS.register(...) block started.
When I later tried to delete the "5 lines before ChartJS.register"
(so I could move the comment to a different position), my old_string
matched the comment by its textual content — but patch was also
fuzzy-matching on the lines AFTER it, which were the import block.
Fuzzy match picked a different region that happened to have the same
trailing pattern, and the comment in that OTHER region got deleted.
Import-silently-dropped pitfall (2026-06-09, pm-system agent/runtime.ts)
Symptom: After a patch that should have only modified a
middle block of agent/runtime.ts, the import { Elysia } from 'elysia'
line at the top of the file vanished. TypeScript compiler reported:
ERROR [358:10] Cannot find name 'Elysia'.
LSP diagnostics showed 30+ noise errors from intermediate-state corruption, so the real issue (missing import) was buried.
Root cause (the bit that actually bit me): My old_string
matched a second occurrence of the import block deeper in the
file (a copy-pasted fragment in a function body, which I had no
reason to know existed because I'd only read_file a windowed
view). patch's fuzzy-match picked that second occurrence, leaving
the actual top-of-file import block in an intermediate state
where the Elysia import line was no longer reachable by
post-patch new_string.
Detection recipe (use this when you see many LSP errors at once):
bun --print 'import("./src/path/file.ts").then(m => Object.keys(m))'
Object.keys returns the expected
exports, the file is fine — LSP is stale.read_file(path) with NO offset/limit)
to see the actual top-of-file imports, then check each
import { X } against every usage site of X in the file.git diff path/to/file — if you see a
deleted import line that you didn't intend to delete, that's
the corruption.Recovery if it happens:
git diff path/to/file to confirm what got dropped.patch is safer than trying to chain more patches
on a partially-broken state).bun --print 'import(...)' to confirm fix.Prevention recipe (extends adjacent-anchor pitfall):
old_string that starts with a bare import {
if the file has multiple import blocks. Anchor on a more specific
pattern (a unique comment, a function signature, the line just
before and just after the target).patch on a file, run
git diff path/to/file | head -30 to eyeball what changed at
the top, even if the patch was supposed to touch only line 50.bun --print 'import(...)'
over LSP diagnostics — the runtime is the source of truth.Why this is dangerous:
Elysia import — only surfaces as ONE
error line among 30+ noise lines, easy to missDetection recipe (use this when you see many LSP errors at once):
bun --print 'import("./src/path/file.ts").then(m => Object.keys(m))'
Object.keys returns the expected
exports, the file is fine — LSP is stale.read_file(path) with NO offset/limit)
to see the actual top-of-file imports, then check each
import { X } against every usage site of X in the file.git diff path/to/file — if you see a
deleted import line that you didn't intend to delete, that's
the corruption.Recovery if it happens:
git diff path/to/file to confirm what got dropped.patch is safer than trying to chain more patches
on a partially-broken state).bun --print 'import(...)' to confirm fix.Prevention recipe (extends adjacent-anchor pitfall):
old_string that starts with a bare import {
if the file has multiple import blocks. Anchor on a more specific
pattern (a unique comment, a function signature, the line just
before and just after the target).patch on a file, run
git diff path/to/file | head -30 to eyeball what changed at
the top, even if the patch was supposed to touch only line 50.bun --print 'import(...)'
over LSP diagnostics — the runtime is the source of truth.Why this is dangerous:
replace_all errors)bun typecheck was clean (deleting a comment is invisible to TS)bun test passed (no behavioural change)git diff --stat showed the right number of lines added/removedPrevention recipe:
read_file(path) (no offset/limit) so the
LLM context has the entire file, not a windowed slice.old_string on a unique line that appears EXACTLY
once in the file — usually a function signature, a unique
identifier, or a comment that's truly one-of-a-kind.patch reports "Found N matches for old_string", NEVER
replace_all=true blindly. Either (a) add 3+ more lines of
surrounding context, (b) split into two smaller patches with
different anchors, or (c) git checkout HEAD -- <file> and
re-patch from scratch.git diff <file> and READ the diff
end-to-end (not just --stat). Comment deletions are silent
if you only look at line counts.Real transcript excerpt:
> patch mode=replace path=ChartBlock.tsx
old_string: "import { Bar, Line, Pie, Doughnut } from 'react-chartjs-2';"
new_string: "import { Bar, Line, Pie, Doughnut } from 'react-chartjs-2';\n\n// Register..."
Result: comment block 7 lines above got deleted, anchor was
re-matched to a second occurrence near `ChartJS.register`
Recovery if it happens: git diff <file> to confirm the deletion,
then git checkout HEAD -- <file> to restore, then re-patch with
the corrected old_string (more unique context).
Scripted detection (use this BEFORE reading the diff manually on any non-trivial patch — catches silent comment deletions):
# Compare the file against HEAD byte-for-byte ignoring whitespace
git show HEAD:path/to/file > /tmp/before.txt
cp path/to/file /tmp/after.txt
# Lines that were deleted (excluding empty deletions = the anchor itself)
diff /tmp/before.txt /tmp/after.txt | grep '^<' | grep -v '^<$' | head -20
# If you see comment lines (start with // or # or /* or *) in the
# "deleted" output that you didn't intend to delete → recovery time
# Quick sanity: line count delta should match what you expected
git show HEAD:path/to/file | wc -l
wc -l path/to/file
# If the delta is way off (>2× what you expected), investigate
# Catches "I deleted a comment but kept the code" case — verifies
# the file's top-level structure (function count, export count) is
# what you think it is
git show HEAD:path/to/file | grep -cE '^(export |function |const \w+ =)'
grep -cE '^(export |function |const \w+ =)' path/to/file
# Should match. Mismatch = structural change you didn't intend.
The "double-match" sub-pattern (2026-06-08, crm-system ChartBlock.tsx,
later in same session): the first replace_all=true patch with an
identical-match anchor silently re-inserted the comment I had just
deleted (because by then there were TWO copies of the comment — the
original + the patch trying to "restore" it). The fix was yet a
THIRD patch with explicit replace_all=true on the now-identical
duplicates. The lesson: replace_all=true is only safe when the
duplicates are intentional and you want both replaced. If you
hit the same anchor twice in the same session, treat it as a
recovery signal — restore from HEAD and start over.
Prevention recipe (extended): if your patch returns
"Found N matches for old_string" AND you've already done one
patch in this session on the same file, STOP and
git diff <file> to see the current state before re-running.
# Find the extra/missing brace causing SyntaxError
python3 -c "
content = open('path/to/file').read()
brace_count = 0
for i, c in enumerate(content):
if c == '{': brace_count += 1
elif c == '}': brace_count -= 1
if brace_count < 0:
print(f'Extra }} at position {i}, line {content[:i].count(chr(10))+1}')
break
if brace_count > 0:
print(f'{brace_count} missing }} at end')
"
# Compare file size before and after patch
git diff HEAD --stat path/to/file
# Isolate the problematic commit
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
Dev-agent / checker-agent collaboration loop driven by downstream project docs/STATE.md. Dev agent implements and records work items; an independent checker agent verifies each item with real lint/typecheck/test/build evidence and writes findings back; loop continues until all items are VERIFIED or escalation limits are hit.
Synchronizes review feedback, QA findings, user corrections, and code-review suggestions into durable project docs before Build, merge, or ship.
Intake workflow for existing projects before continuing development. Analyze current source state, derive a truthful docs baseline, identify QA/regression gaps, and create a safe continuation plan.
防止修復過的 bug 重新出現(regression)。 規則:每個修過的 bug 必須留下「regression test」+「root cause note」+「為何會發生」分析, 確保日後 refactor / 改需求時唔會重新踩坑。 David 在 2026-06-06 kanban task 明確指出「舊的 bug 又出現」嘅困擾。
定時壓縮長時間任務的 context，避免 token 爆炸。寫入 context-summary.md 保留決策和當前狀態，丢棄細節。
Task Orchestration Subagent — Coordinates all subagents, manages task board, handles parallel/sequential execution, tracks dependencies and failures. The conductor of the development orchestra.