agentleFS
xsovad06xsovad06/sova/.agents/skills/sova-rearrange-commits/SKILL.md

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

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
  1. Distinctive:

    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 …

    line 29
  2. Distinctive:

    Commit any uncommitted changes as a WIP commit (review git status first, so nothing that must not be committed, such as secrets or scratch …

    line 31
  3. Very specific:

    Create a uniquely named backup branch and note the printed name, since later blocks re-assign BACKUP to it.

    line 38
  4. Distinctive:

    All changes, including the WIP snapshot, are now unstaged in the working tree.

    line 54
  5. Distinctive:

    All changes are committed (nothing left uncommitted, no WIP commit left in the history)

    line 119
  6. Very specific:

    If the branch must also be brought up to date with the base, rebase it now, while the backup still exists.

    line 126
  7. Distinctive:

    Only once the rearranged (and, if rebased, verified) history holds, delete the backup:

    line 137
  8. Very specific:

    Before PR: Run the sova-review skill after rearranging, then the sova-pr skill

    line 147
  9. Distinctive:

    Keep commits small: easier to review and revert

    line 153
  10. Distinctive:

    Never create standalone doc-count commits (e.g., "docs: update counts"): fold doc/count updates into the commit that introduced the change …

    line 154
  11. Distinctive:

    NEVER use emojis in any output

    line 155

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 status

Step 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.

  1. Commit any uncommitted changes as a WIP commit (review git status first, 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
  2. Create a uniquely named backup branch and note the printed name, since later blocks re-assign BACKUP to 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"
  3. Soft reset to the point where this branch forked from the base, and note the printed SHA. Use the fork point (git merge-base), not origin/$BASE itself: 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.
    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 .
    All changes, including the WIP snapshot, are now unstaged in the working tree.

Step 3: Create Small, Logical Commits

Group changes by logical unit and commit in order:

  1. Schema/model/migration changes first
  2. Core logic/services second
  3. API/views/controllers third
  4. Tests fourth
  5. 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 --stat

git 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 --abort and report the conflicting files; the branch is back to the rearranged history.
  • After a rebase that moved the branch: git diff "origin/$BASE"...HEAD --stat must list only this branch's files, and bash 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-full skill (Phase 3) and the sova-pr skill (commit organization step)
  • Before PR: Run the sova-review skill after rearranging, then the sova-pr skill

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.