Resuming and recovering
Every run starts by working out where an earlier run stopped. Use the context output: branch, upstream ahead/behind, working-tree status, and existing PRs. Then continue from the first step that is still incomplete. Never redo a step that already succeeded.
Resume points
| Observed state | Resume at |
|---|---|
| No changes, no unpushed commits, and the PR is open and current | Nothing to do. Report the branch, the PR, and that everything is in sync. |
| No changes, and the branch was never pushed and has no PR | Nothing to publish. Say so. |
| A clean tree with commits ahead of the upstream, or a branch never pushed | Verify the commits you're about to push (scan.sh --range <target>/<base>..HEAD, plus checks unless --skip-checks), then go to the approval gate. |
| Pushed and in sync, with no open PR | Approval gate for PR creation only. |
| Pushed with an open PR, plus new local changes | Plan and commit the new changes, then push. The existing PR updates with the push. |
| A staged index left from an interrupted run | Treat it as user-staged content (see commits.md). Ask if you can't tell what it is. |
| Behind the upstream with no local-only commits | git merge --ff-only @{u}. If the dirty tree blocks it, report that. |
| The local and remote branches have diverged | Stop. Show both sides and ask. |
| A merge, rebase, or cherry-pick is in progress | Stop. Report it, and don't run --continue or --abort unless the user asks. |
Failures during the run
- A commit hook rejects a commit: The commit didn't happen and the index is unchanged. Fix the cause only if your changes caused it, then commit again. Otherwise stop, and report which commits exist and what remains staged.
- A commit fails partway through the plan: Report which commits were created and which changes are left. Don't roll back the commits that succeeded.
- You staged the wrong content before committing: Remove only what you staged, with
git restore --staged -- <path>orgit apply --cached -R <patch>. Then check thatgit diffstill shows the user's unstaged work. - One of your own unpublished commits is wrong: You may fix it with
git commit --amendorgit reset --soft HEAD~1. Confirm withgit branch -r --contains <sha>that no remote branch has it yet. Never do this to commits you didn't create in this run. - The push is rejected: Follow the push section of
github.md. No force-push. - The push succeeded but PR creation failed: Check for an existing PR, then retry
gh pr create. If that still fails, give the compare URL. The report must state that the branch is pushed and the PR is not open. - A network error or timeout: Re-check the actual state before retrying (
git ls-remote <remote> <branch>,gh pr list). The operation may have succeeded anyway.
Avoiding duplicates
- Before committing: If
git statusshows nothing staged for a planned commit, skip that commit; never create an empty one. If an equivalent change is already on the branch or its remote (git cherry -v <remote-branch>), don't commit it again. - Before creating a PR: Always query for an existing open PR.
- Before pushing: If
git ls-remotealready shows the local HEAD, skip the push and report it as already pushed.