retrofit-commit
Skill0 starsChanged 24 days agoMITView on GitHub
Retrofits uncommitted refactors into the existing commits of a feature branch, so the history reads as if the code had been written correctly from the start. Use when the user has already committed a feature and then refactored/fixed/adjusted that same code, and wants those changes folded back into the original commits instead of appended as new ones. Triggers on "fix commits", "fixup", "dar fixup", "jogar essa mudança pro commit original", "rebase -i", "reescrever a história", "como se tivesse sido feito desde o começo", "esse arquivo não deveria existir", or any request to reorganize/rewrite an existing branch's history.
In this repository5 other files it gives its agents.
- atomic-commitSkill
- e2e-reviewSkill
- humanizerSkill
- open-prSkill
- reviewSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
If commit #35 edits _dequeue, you cannot delete _dequeue in a fixup at #8: #35 will fail to replay.
- Distinctive: line 50
When rules 2/3 push a change onto a late commit, semantic precision suffers.
- Distinctive: line 54
When a change makes commit A depend on something introduced later in commit B, the instinct is to split the change in two.
- Distinctive: line 89
Never hand the user a sequence you have not replayed.
- Very specific: line 99
When handing over, drop GIT_SEQUENCE_EDITOR and let the user's editor open: autosquash arrives with the plan already positioned, so they …
- Very specific: line 103
Only rewrite mode needs a GIT_SEQUENCE_EDITOR script — autosquash cannot drop, split, reorder or rename commits.
- Very specific: line 128
Stop with a clean tree (an edit that applied): the commit exists → git commit --amend is correct.
- Very specific: line 129
Stop with conflict markers (UU/DU/AA): the commit does not exist yet → --amend will silently fold your work into the *previous* commit and …
- Very specific: line 135
If you script conflict resolution, beware patterns like (?:\s+'.*?\n)* meant to match a key's continuation lines — they happily eat the …
- Distinctive: line 158
Run these as separate one-purpose commands rather than one block.
- Distinctive: line 186
All of them need a force-push once rewritten.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
retrofit-commit
The user built a feature across many commits, then refactored that same code. The refactor must disappear into the original commits: whoever reads the final history should see the feature built correctly the first time, with no trace of the intermediate design.
This is NOT atomic-commit (which organizes new work into new commits). Here every change is absorbed into commits that already exist.
The two modes
Decide this first — it changes everything downstream.
Fixup mode. The original commits were right, they just need adjusting. Let git name and place the commits for you: git commit --fixup=<target-sha> produces fixup! <subject>, and git rebase -i --autosquash <base> positions and marks every one of them on its own. No hand-written todo, no sequence editor, nothing to get wrong. The target commit survives.
Rewrite mode. The refactor says something should never have existed — a module deleted, a function that moved, a layer collapsed. A fixup cannot express this: it only adds a later diff, so the artifact still appears and then disappears. You must rewrite the original commits so the artifact never appears at all, which may drop, split, reorder or rename them.
The tell: if the user says "that file doesn't exist anymore, so that commit shouldn't exist either", they want rewrite mode. Ask which mode when a deletion or a move is involved — fixup mode silently produces a create-then-delete history, which is exactly what they are trying to avoid.
The three rules that prevent every conflict
These were learned the hard way. Violating any of them produces cascading conflicts that are not worth "resolving" — restructure instead.
Rule 1 — a fixup can only touch code that exists at its target. The fixup is applied at the target commit's position. Files created by later commits do not exist there. Before committing anything, verify:
for f in $(git diff --cached --name-only); do
git cat-file -e <target>:"$f" 2>/dev/null || echo "NOVO: $f"
done"NOVO" is fine only for files the fixup itself creates, or files created by an earlier fixup in your own sequence.
Rule 2 — code you delete must be deleted at or after the last commit that touches it.
If commit #35 edits _dequeue, you cannot delete _dequeue in a fixup at #8: #35 will fail to replay. Find the real last toucher:
git log --reverse --format='%h %s' <base>..HEAD -S'<symbol>' -- <paths>Rule 3 — the fixup's diff carries context from the branch tip, not from the target. Even with the right target, if neighbouring lines changed between target and tip, the 3-way merge conflicts. The safe default: target the last commit that touches that file, so tip content and target content are identical. Check with:
git log --reverse --format='%h %s' <base>..HEAD -- <file>When rules 2/3 push a change onto a late commit, semantic precision suffers. Say so explicitly rather than silently accepting a bad attribution — and offer reordering (below) as the fix.
Reordering beats splitting
When a change makes commit A depend on something introduced later in commit B, the instinct is to split the change in two. Usually the right answer is to move B before A and let A be born correct.
Concretely: bootstrap was introduced before upsert, and the refactor made bootstrap call upsert. Splitting gives two half-changes; moving upsert earlier gives one complete change and a history where bootstrap never had the inline version. Prefer the reorder. When you reorder, the moved commit may have to take over creating a file the other one used to create.
A broken intermediate commit is worse than a conflict
A conflict costs the user a minute. A commit that imports a symbol that no longer exists breaks git bisect silently. Never remove a function in an earlier commit than its callers — keep the old code alive, duplicated if necessary, until the commit that removes its last caller. Transient dead code and transient duplication are acceptable; a broken import is not.
Execution
Work on the branch, not in your head.
Confirm where you are, and that nobody moved it. The user may be working in this repo from another terminal while you plan. Never trust a branch name you read minutes ago:
git symbolic-ref -q HEAD || echo "DETACHED"
git reflog HEAD --date=iso | head -10git status -sb printing ## HEAD (no branch) usually means someone ran git checkout origin/<branch> — checking out a remote-tracking ref detaches HEAD. If the reflog shows wip, reset or commit entries that are not yours, the tree you analysed is not the tree you are about to rewrite: re-read before continuing.
Snapshot immediately before the rebase, not at the start of the analysis — otherwise you back up a state the user has since moved past, and restoring it would destroy their work. This is what lets you restart without losing anything:
git add -A
T=$(git stash create "target"); git update-ref refs/tmp/target "$T"; git reset
git update-ref refs/tmp/backup HEADrefs/tmp/target is the ground truth for the final state. Every verification compares against it.
Then reset the working tree and rebuild the commits forward, one per target, in the chronological order of their targets so their diffs stack correctly.
Dry-run the rebase before handing it over
Never hand the user a sequence you have not replayed. In fixup mode there is no todo to write — replay on a throwaway branch, compare against the snapshot, then run the same command for real:
git checkout -q -B tmp/test HEAD
GIT_SEQUENCE_EDITOR=true GIT_EDITOR=true git rebase -i --autosquash <base>
git diff refs/tmp/target tmp/test --stat # must be emptyZero conflicts is the target. If it conflicts, do not resolve — go back and fix the targets.
When handing over, drop GIT_SEQUENCE_EDITOR and let the user's editor open: autosquash arrives with the plan already positioned, so they only read and save instead of typing fixup on N lines.
Writing the todo by hand (rewrite mode only)
Only rewrite mode needs a GIT_SEQUENCE_EDITOR script — autosquash cannot drop, split, reorder or rename commits.
The todo format is not pick <sha> <subject>. Git 2.55 writes the subject behind a # , and appends # empty to empty commits:
pick aa083ba # first subject
pick 15dc91b # second subject # emptySo never match on subject text; the sha is the only stable field. Key your target map by sha.
Assert the parse before writing the file. If the number of pick lines you recognised is not git rev-list --count <base>..HEAD, abort saying exactly that. A parser that recognises nothing writes back an unchanged todo, and the rebase then runs the original plan — a silent success indistinguishable from a real one. Word the failure after the cause: "parsed 0 of 26 pick lines" points at the format, while "could not find my fixup lines" sends you hunting through subjects that were never the problem.
sed -i is the obvious way to write these scripts and usually works. On some mounts it does not — sshfs, for one, refuses the permission-preserving rename and prints sed: preserving permissions for '.git/rebase-merge/sedXXXX': Operation not permitted, after which the todo is silently unedited and the rebase runs the original plan. If you see that, or if a rebase completes without doing what you asked, rewrite the editor in Python (open(path).read() → transform → open(path,'w').write(...)), which edits in place and does not touch permissions.
The same message on a source file (sed: preserving permissions for 'src/sedXXXX') is harmless noise — the content is written. Confirm with git diff rather than trusting or distrusting the message.
The --amend trap
At a rebase stop, check whether the commit exists before amending:
git log --oneline -1 && git status --short- Stop with a clean tree (an
editthat applied): the commit exists →git commit --amendis correct. - Stop with conflict markers (
UU/DU/AA): the commit does not exist yet →--amendwill silently fold your work into the previous commit and destroy the one being applied. Resolve, thengit commit -C <original-sha>to create it with its original message and author.
This mistake is easy to make and hard to spot afterwards. Check every time.
Regex on conflict blocks
If you script conflict resolution, beware patterns like (?:\s+'.*?\n)* meant to match a key's continuation lines — they happily eat the following entries too. Always diff the result against refs/tmp/target afterwards; that check is what catches it.
Verification (all of it, every time)
# 1. final tree must equal the snapshot
git diff refs/tmp/target HEAD --stat # must be empty
# 2. every commit must parse
for c in $(git rev-list <base>..HEAD); do
for f in $(git show --pretty= --name-only --diff-filter=ACMR $c | grep '\.py$'); do
git show "$c:$f" | python -c "import ast,sys; ast.parse(sys.stdin.read())" || echo "ERRO $c $f"
done
done
# 3. no commit may import a symbol that does not exist there (bisect safety)
# resolve the module path and look for def/class/assignment — not just `def`
# 4. in rewrite mode, the removed artifacts must appear in ZERO commits
git log --oneline <base>..HEAD -S'<symbol>' -- conversis/ tests/
git log --oneline <base>..HEAD -- <deleted-file>Run these as separate one-purpose commands rather than one block. Permission classifiers routinely deny long compound shell scripts, and a denial halfway through verification is indistinguishable from a failure.
Distinguish problems you introduced from ones that were already there: re-run the check against the pre-rewrite backup before reporting anything as a regression. Report pre-existing issues as pre-existing.
Sibling branches
Stacked branches (eduardo/feature-part-1, part-2) point into the middle of this history. Two ways to keep them right:
- Rebase from a base after them, so their commits are never rewritten — simplest when all targets are late.
--update-refs, which moves them along. It composes with everything else:git rebase -i --autosquash --update-refs <base>.
Find them first — a ref you did not notice is a ref you orphan — and back up the ones inside the range:
for r in $(git for-each-ref --format='%(refname:short)' refs/heads); do
git merge-base --is-ancestor "$r" HEAD 2>/dev/null &&
git merge-base --is-ancestor <base> "$r" 2>/dev/null &&
echo "$r $(git log --oneline -1 "$r")"
done
git update-ref refs/tmp/backup-<sibling> <sibling>Afterwards confirm they are still ancestors:
git merge-base --is-ancestor <sibling> HEAD && echo OKAll of them need a force-push once rewritten. Say so.
Reporting
Give the user a table of change → target commit. Call out explicitly:
- any target chosen for conflict-avoidance rather than semantics, and why
- commits that became empty and were dropped
- commits that were reordered, split or renamed
- what you could not verify (test suites that will not run in the environment)
Then leave the backup refs in place and tell them how to delete them:
git for-each-ref --format='%(refname)' refs/tmp | xargs -n1 git update-ref -dDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

