# Git Branch Redo From Scratch > Use when a branch or proof of concept should be redone from scratch: throw away the approach, start implementation over, and treat tests as the spec. - Skill: `tony/git-branch-redo-from-scratch` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add tony/git-branch-redo-from-scratch` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/git-branch-redo-from-scratch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/git-branch-redo-from-scratch --- # Redo from scratch Throw the implementation away and write it again, without losing what the original learned. Argument: $ARGUMENTS — a PR number, a branch, a statement of what should change about the approach, or nothing. Four references carry the parts that must not drift: - `references/rebuild-contract.md` — the contract, the coverage ledger, reconciliation, and what counts as done. - `references/branch-safety.md` — the gates, the backup, recovery, and the push. - `references/commit-messages.md` — style discovery, intent recovery, and the privacy gate. - `references/rebase-toolkit.md` — per-commit verification with no editor. ## Core principle The old branch is the specification, not the source. A redo that reads the old implementation line by line and retypes it has reproduced the shape it was called in to replace. Work from what the branch had to *achieve*; consult how it achieved it only when the requirement is ambiguous. ## Boundary the `git-branch-soft-reset-and-recommit` skill keeps the net change identical and rebuilds only the history. Reach for it when the code is right and the commits are wrong. This skill is the opposite trade: the history and the code are both replaced, and the net change may differ. That makes it strictly riskier, so it earns its safety from the contract rather than from a tree comparison. ## Phase 1 — Establish the contract before anything else Per `rebuild-contract.md`. Identify trunk's tests, the tests this branch added or changed, and run them against the branch now. What passes is the specification; what is already failing or skipped is a finding to report, not a target. **If the branch has no tests, stop here.** An untested branch has no mechanical invariant, and a redo becomes a rewrite with review as the only net. Offer to write characterization tests against the existing implementation first, so a spec exists before anything is discarded. Proceed without them only if the user says so, and say in the final report that nothing mechanical was guarding the result. ## Phase 2 — Study the branch into a ledger Build the coverage ledger from `rebuild-contract.md`: behavior changes, tests, edge cases and workarounds, review requests, ticket acceptance criteria, public surface, dependencies. Mine intent per `commit-messages.md` Part 2 — commits, trailers, the pull request and its review threads, linked tickets, and optionally the session that wrote the code, under the privacy rules there. Give the workarounds disproportionate attention. A guard with no test and no comment is the single most likely thing a clean rewrite drops, and the original author usually had a reason they never wrote down. ## Phase 3 — Gate and back up Every refusal in `branch-safety.md`. Then record the original tip so it cannot be lost: ``` git branch "backup/-$(date -u +%Y%m%dT%H%M%SZ)" ``` The old branch is never deleted, never force-moved, and never the place the rebuild happens. ## Orchestration Plan Enter plan mode before writing any code. In Claude Code that is `EnterPlanMode`; in other hosts `/plan` or Shift+Tab. If plan mode is unavailable, present the same plan inline and wait for a go-ahead. The plan states: - The contract: which tests are the spec, and their current result. - The ledger, summarized, with the entries judged highest-risk called out by name. - What is being changed about the approach, and why the original shape is not being kept. - Where the rebuild happens — the worktree path and new branch name. - The gate commands discovered from the project's own conventions. - Anything the branch does that the rebuild intends to drop, as an explicit list to be approved rather than discovered later. When more than one approach is genuinely in contention, say so and offer a bakeoff rather than picking silently. Wait for approval. Exit plan mode before executing. ## Phase 4 — Rebuild Work in a worktree so the original branch is untouched and remains runnable for comparison: ``` git worktree add -b -redo /tmp/redo ``` Rebuild against the ledger, in the project's idiom, with no commits until the contract is met — the exploration is a spike, and unreviewed exploration does not belong in history. Mark shortcuts in place as you take them so they become commits or decisions, not silent debt. When the plan called for a bakeoff and the `spike` plugin is installed, the `spike-bakeoff` skill runs the competing strategies in isolated worktrees and returns a scored comparison. Without it, build the leading candidate, record what the alternatives were, and say they were not tried. ## Phase 5 — Verify against the contract Trunk's tests, then the branch's tests, unmodified. A test the rebuild cannot pass without editing is a decision, not a task. Stop and surface it: the choices are to fix the rebuild, or to agree the test encoded something the new approach deliberately changes. Never edit a spec test to make a rebuild green. `` is the absolute path to `references/rebase-todo.sh`, which ships with this skill. A shell runs with your project as its working directory, not this skill's, so substitute the full path before invoking it. Then gate every commit of the new series in place: ``` sh verify '' ``` ## Phase 6 — Reconcile Walk the ledger. Every entry is addressed, deliberately dropped, or missed. A drop is recorded in the commit message that drops it; a miss is a defect. Then present the comparison as review material, never as a gate: ``` git diff -redo ``` Each hunk where the old branch did something the new one does not is a question for the user. This is where a lost workaround surfaces. ## Phase 7 — Land, then stop Commit the rebuild as an atomic series in the project's own format, per `commit-messages.md`. Report the ledger outcome, the contract result, the backup branch, and every deliberate drop. Pushing is a separate decision, with the flags from `branch-safety.md`. The old branch stays until the user retires it. ## Rules - Never edit a test the branch added in order to make the rebuild pass, without explicit approval. - Never delete or force-move the original branch. - Never rebuild in the original branch's worktree. - Never present a passing test run as proof of completeness; the ledger covers what the tests missed. - Never commit during the rebuild phase. - Language-agnostic: every gate command comes from the project's own conventions files. ## Common mistakes **Retyping the old implementation.** The result is the same shape with new commit hashes. Build from the ledger. **Treating `git diff` against the old branch as a gate.** The code is supposed to differ. It is a list of questions. **Dropping a guard that had no test.** It usually marks a bug someone already hit. Every workaround is load-bearing until its ledger entry says otherwise. **Starting without a contract.** On an untested branch this skill's first job is to create one, not to rebuild. **Rebuilding a branch that only needed its commits redone.** If the code is right and the history is wrong, that is the `git-branch-soft-reset-and-recommit` skill, and it comes with a guarantee this skill cannot offer. ## Portability notes - `$ARGUMENTS` — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none. - Bundled files — every relative path in this skill points at a file shipped inside this skill directory. Read them from here, not from the host's plugin tree.