sova-rearrange-commits
Skill3 starsChanged 8 days agoApache-2.0View on GitHub
Reorganize current branch commits into small, logical, well-documented steps.
- Deletes or force-pushes
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- dashboard-designSkill
- database-patternsSkill
- design-systemSkill
- design-tasteSkill
- issue-templateSkill
- sova-address-prSkill
- sova-after-mergeSkill
- sova-agent-readinessSkill
- sova-audit-instructionsSkill
- sova-debugSkill
- sova-develop-explainSkill
- sova-develop-fullSkill
- sova-developSkill
- sova-extract-knowledgeSkill
- sova-find-taskSkill
- sova-health-auditSkill
- sova-ingest-reviewSkill
- sova-integrate-prSkill
- sova-issueSkill
- sova-new-featureSkill
- sova-optimize-knowledgeSkill
- sova-prSkill
- sova-researchSkill
- sova-review-fullSkill
- sova-review-prSkill
- sova-reviewSkill
- sova-simplifySkill
- sova-specSkill
- sova-standupSkill
- sova-statusSkill
- sova-testSkill
- sova-update-docsSkill
- testing-patternsSkill
- visual-auditSkill
- dashboard-designSkill
- database-patternsSkill
- design-tasteSkill
- issue-templateSkill
- testing-patternsSkill
- visual-auditSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 29
Never use git stash here: the stash stack is shared by every worktree and session of this repository, so a pop can restore someone else's …
- Distinctive: line 31
Commit any uncommitted changes as a WIP commit (review git status first, so nothing that must not be committed, such as secrets or scratch …
- Very specific: line 38
Create a uniquely named backup branch and note the printed name, since later blocks re-assign BACKUP to it.
- Distinctive: line 54
All changes, including the WIP snapshot, are now unstaged in the working tree.
- Distinctive: line 119
All changes are committed (nothing left uncommitted, no WIP commit left in the history)
- Very specific: line 126
If the branch must also be brought up to date with the base, rebase it now, while the backup still exists.
- Distinctive: line 137
Only once the rearranged (and, if rebased, verified) history holds, delete the backup:
- Very specific: line 147
Before PR: Run the sova-review skill after rearranging, then the sova-pr skill
- Distinctive: line 153
Keep commits small: easier to review and revert
- Distinctive: line 154
Never create standalone doc-count commits (e.g., "docs: update counts"): fold doc/count updates into the commit that introduced the change …
- Distinctive: line 155
NEVER use emojis in any output
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Rearrange Commits
Reorganize all commits on the current branch into clean, logical, atomic commits.
Instructions
Step 1: Analyze Current State
Resolve the base branch at runtime rather than assuming main. Every shell block runs in a fresh shell, so each block below that uses BASE re-assigns it first. Fall back to the repo default only when gh pr view confirms there is no PR for this branch yet; abort on any other failure (auth, network, API) instead of guessing:
BASE=$(gh pr view --json baseRefName --jq .baseRefName 2>&1) || { case "$BASE" in *"no pull requests found"*) BASE=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) ;; *) echo "Unable to resolve the base branch: $BASE" >&2; exit 1 ;; esac; }
[ -n "$BASE" ] || { echo "Unable to resolve the base branch" >&2; exit 1; }
echo "Base branch: $BASE"
git fetch origin || { echo "Fetch failed: STOP, origin/$BASE may be stale" >&2; exit 1; }
git branch --show-current
git log "origin/$BASE"..HEAD --oneline
git diff "origin/$BASE"...HEAD --stat
git statusStep 2: Preserve All Changes
Never use git stash here: the stash stack is shared by every worktree and session of this repository, so a pop can restore someone else's changes. Commit uncommitted work instead, and keep a backup branch until the rearranged history is verified.
- Commit any uncommitted changes as a WIP commit (review
git statusfirst, so nothing that must not be committed, such as secrets or scratch files, is included):if [ -n "$(git status --porcelain)" ]; then git add -A && git commit -m "chore: WIP snapshot before rearrange" \ || { echo "WIP commit failed (hook, signing or staging error): STOP, nothing was reset" >&2; exit 1; } fi - Create a uniquely named backup branch and note the printed name, since later blocks re-assign
BACKUPto it. The tree must be fully committed first, or the Step 4 recovery would drop the uncommitted work:[ -z "$(git status --porcelain)" ] || { echo "Uncommitted changes remain: STOP before creating the backup" >&2; exit 1; } BACKUP="backup/rearrange-$(date +%s)-$$-$RANDOM" git branch "$BACKUP" || { echo "Failed to create backup branch $BACKUP: STOP before resetting" >&2; exit 1; } echo "Backup branch: $BACKUP" - Soft reset to the point where this branch forked from the base, and note the printed SHA. Use the fork point (
git merge-base), notorigin/$BASEitself: if the base branch moved since this branch was last rebased, committing the branch's tree on top of the newer base would silently revert everything the base gained in between.
All changes, including the WIP snapshot, are now unstaged in the working tree.BASE=$(gh pr view --json baseRefName --jq .baseRefName 2>&1) || { case "$BASE" in *"no pull requests found"*) BASE=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) ;; *) echo "Unable to resolve the base branch: $BASE" >&2; exit 1 ;; esac; } [ -n "$BASE" ] || { echo "Unable to resolve the base branch" >&2; exit 1; } FORK_POINT=$(git merge-base HEAD "origin/$BASE") echo "Fork point: $FORK_POINT" git reset --soft "$FORK_POINT" git reset HEAD .
Step 3: Create Small, Logical Commits
Group changes by logical unit and commit in order:
- Schema/model/migration changes first
- Core logic/services second
- API/views/controllers third
- Tests fourth
- Configuration/misc last
Commit Message Format
type(scope): short description
Detailed explanation of WHAT, WHY, and HOW.Types and scopes come from the project's commit format invariant (for example invariants/commit-format.sh) or AGENTS.md; use only those. A common set is feat, fix, refactor, test, docs, chore, ci (ci alone may omit the scope). Do NOT invent types such as perf or new scopes: pre-push hooks reject them. The scope names the directory the diff actually touches, not a semantically related area.
Step 4: Verify
BACKUP=<backup branch printed in Step 2>
FORK_POINT=<fork point printed in Step 2>
git status --porcelain
git diff "$BACKUP"
git log "$FORK_POINT"..HEAD --oneline
git diff "$FORK_POINT"...HEAD --statgit status --porcelain and git diff "$BACKUP" MUST both print nothing: the rearranged branch must have exactly the tree it had before. If either prints anything, restore the original history and start again from Step 2.3. Restore through the block below, never a bare git reset --hard: an edit made while recreating commits in Step 3 exists only in the working tree, not in $BACKUP, so the block first commits anything uncommitted to a rescue branch, which you inspect and carry forward:
BACKUP=<backup branch printed in Step 2>
if [ -n "$(git status --porcelain)" ]; then
git add -A && git commit -m "chore: WIP rescue before re-reset" \
|| { echo "Rescue commit failed: STOP, do not reset over uninspected changes" >&2; exit 1; }
RESCUE="rescue/squash-$(date +%s)-$$-$RANDOM"
git branch "$RESCUE" || { echo "Failed to create rescue branch $RESCUE: STOP" >&2; exit 1; }
echo "Rescue branch: $RESCUE"
fi
git reset --hard "$BACKUP"Then confirm the rearrangement kept what the base gained. The two checks above cannot see this: a reset that wrongly targeted origin/$BASE leaves the tree identical, so git diff "$BACKUP" stays empty while the branch's diff now reverts everything the base gained since the fork point. The block must end by printing File-set check passed; if it stops instead, restore the backup as above and start again from Step 2.3:
BASE=$(gh pr view --json baseRefName --jq .baseRefName 2>&1) || { case "$BASE" in *"no pull requests found"*) BASE=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) ;; *) echo "Unable to resolve the base branch: $BASE" >&2; exit 1 ;; esac; }
[ -n "$BASE" ] || { echo "Unable to resolve the base branch" >&2; exit 1; }
BACKUP=<backup branch printed in Step 2>
OLD_FORK=$(git merge-base "$BACKUP" "origin/$BASE") || { echo "Cannot resolve the backup's fork point: STOP" >&2; exit 1; }
NEW_FORK=$(git merge-base HEAD "origin/$BASE") || { echo "Cannot resolve HEAD's fork point: STOP" >&2; exit 1; }
BEFORE=$(git diff --name-only "$OLD_FORK" "$BACKUP") || { echo "git diff failed: STOP" >&2; exit 1; }
AFTER=$(git diff --name-only "$NEW_FORK" HEAD) || { echo "git diff failed: STOP" >&2; exit 1; }
BASE_CHANGED=$(git diff --name-only "$OLD_FORK" "origin/$BASE") || { echo "git diff failed: STOP" >&2; exit 1; }
# A file the squash newly brought into the branch's diff that the base changed since the fork is a reverted base change.
REVERTED=$(comm -12 <(comm -13 <(sort <<<"$BEFORE") <(sort <<<"$AFTER")) <(sort <<<"$BASE_CHANGED"))
if [ -n "$REVERTED" ]; then printf 'Squash reverted base changes in:\n%s\nSTOP\n' "$REVERTED" >&2; exit 1; fi
echo "File-set check passed"Ensure:
- All changes are committed (nothing left uncommitted, no WIP commit left in the history)
- Each commit is atomic and self-contained
- Commits are in logical order
- The total diff matches what it was before reorganization
Step 5: Rebase (optional), Then Delete the Backup
If the branch must also be brought up to date with the base, rebase it now, while the backup still exists. This is a fresh shell, so resolve BASE again rather than relying on Step 1's value:
BASE=$(gh pr view --json baseRefName --jq .baseRefName 2>&1) || { case "$BASE" in *"no pull requests found"*) BASE=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) ;; *) echo "Unable to resolve the base branch: $BASE" >&2; exit 1 ;; esac; }
[ -n "$BASE" ] || { echo "Unable to resolve the base branch" >&2; exit 1; }
git fetch origin || { echo "Fetch failed: STOP" >&2; exit 1; }
git rebase "origin/$BASE"- Conflicts: resolve each file's markers,
git add <file>,git rebase --continue. If a conflict cannot be resolved with confidence,git rebase --abortand report the conflicting files; the branch is back to the rearranged history. - After a rebase that moved the branch:
git diff "origin/$BASE"...HEAD --statmust list only this branch's files, andbash invariants/silent-revert-guard.sh . "$BASE"must pass when the project has it. An unrelated file or a deletion far beyond this branch's scope is a silent revert of the base:git reset --hard "$BACKUP"and redo the rebase.
Only once the rearranged (and, if rebased, verified) history holds, delete the backup:
BACKUP=<backup branch printed in Step 2>
git branch -D "$BACKUP"Cross-References
- Called by: the
sova-develop-fullskill (Phase 3) and thesova-prskill (commit organization step) - Before PR: Run the
sova-reviewskill after rearranging, then thesova-prskill
Rules
- Each commit = ONE logical change
- Earlier commits should not depend on later ones
- Keep commits small: easier to review and revert
- Never create standalone doc-count commits (e.g., "docs: update counts"): fold doc/count updates into the commit that introduced the change (the one that added the service, step, test, etc.)
- NEVER use emojis in any output
Does 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.

