Menu
Git branching, merge safety, and commit hygiene for feature development
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Step 2 — Architecture and domain design, one feature at a time
Step 1 — discover requirements through stakeholder interviews and write Gherkin acceptance criteria
Generate and update architecture diagrams, living glossary, and system overview from existing project docs
Enforce code quality using ruff, pytest coverage, and static type checking
Create pull requests with conventional commits, proper formatting, and branch workflow
Flow protocol — design and operate state machine workflows with FLOW.md + WORK.md
| name | version-control |
| description | Git branching, merge safety, and commit hygiene for feature development |
| version | 1.0 |
| author | software-engineer |
| audience | software-engineer |
| workflow | git-management |
This skill governs all Git operations during feature development. The software-engineer owns branch creation, commit hygiene, merging to main, and post-mortem branch management.
These rules are absolute. Violating them risks destroying shared history or losing work.
git push --force and git push --force-with-lease are forbidden.origin, do not git rebase -i, git commit --amend, or git reset --hard on it. These commands rewrite history that others may have fetched.git revert to undo: If a commit on a pushed branch must be undone, create a new revert commit. This appends history safely.main: All feature work happens on branches. main receives code only via --no-ff merge from an approved feature branch.main ──●────────────────────────────●─────►
\ /
\── feat/<stem> ──●──●──●/
mainmain with --no-ff after Step 5 acceptancemain ──●─────●───────────────────────●─────►
\ / /
\ / /
● (start commit) /
\── fix/<stem> ──●──●──●/
fix/<stem> from that commitfix/<stem>main with --no-ffRun at the start of Step 2 (before the system-architect writes stubs).
# Ensure you are on main and it is up to date
git branch --show-current # must output: main
git fetch origin main
git merge --ff-only origin/main # fast-forward only; if this fails, main has diverged — escalate
# Create and switch to feature branch
git checkout -b feat/<feature-stem>
# Push the branch to origin (establishes tracking)
git push -u origin feat/<feature-stem>
Branch naming:
feat/<feature-stem> — new featurefix/<feature-stem> — post-mortem restart of a failed featuredocs/<scope> — documentation-only changeschore/<scope> — tooling, deps, CIIf main has unmerged work: The git merge --ff-only will fail. This means main is ahead of your local copy. Escalate to the PO or SA — do not resolve by merging or rebasing on your own.
Every commit on a feature branch must follow conventional commits:
<type>(<scope>): <description>
Types: feat, fix, test, refactor, chore, docs, perf, ci
Forbidden commit messages (reject immediately if you are tempted to use them):
wip, temp, fix tests, oops, try again, asdfCommit early, commit often: A feature branch with 10 small, well-described commits is better than 1 giant commit. But do not commit broken code (tests must pass at each commit during Step 3).
Run before every session start and before every handoff.
# Verify you are on the correct branch
git branch --show-current # expect: feat/<feature-stem> or fix/<feature-stem>
# Verify working tree is clean
git status # expect: "nothing to commit, working tree clean"
# Verify branch is ahead of main (has commits)
git log main..HEAD --oneline # expect: 1+ commits listed
If any check fails:
git checkout feat/<feature-stem> (or create it if missing)Run after PO acceptance (Step 5). This is the only way code enters main.
# Ensure feature branch is clean and all commits are pushed
git status # must be clean
git push origin feat/<feature-stem>
# Switch to main and update it
git checkout main
git fetch origin main
git merge --ff-only origin/main
# Check for merge conflicts before the real merge
git merge-tree $(git merge-base HEAD feat/<feature-stem>) HEAD feat/<feature-stem>
# If the output is non-empty, there are conflicts. Resolve them on the feature branch first.
# Merge with --no-ff to preserve feature boundary
git merge --no-ff feat/<feature-stem> -m "feat(<scope>): merge <feature-stem> to main"
# Push main
git push origin main
# Delete the feature branch (optional, but recommended)
git branch -d feat/<feature-stem>
git push origin --delete feat/<feature-stem>
Why --no-ff: Fast-forward merges erase the feature boundary from history. With --no-ff, the merge commit groups all feature commits together, making the feature revertible as a single unit.
Run when a feature fails acceptance and the PO restarts it at Step 2.
# Find the feature's original start commit
# The start commit is the commit where the feature branch was created from main.
# It is typically the first commit on the old feature branch.
git log --all --grep="feat(<feature-stem>)" --oneline
# Or, if the branch still exists:
git log --reverse main..feat/<feature-stem> --oneline # first line = start commit
# Checkout the start commit and create fix branch
git checkout -b fix/<feature-stem> <start-commit-sha>
# Commit the post-mortem as the first commit on the new branch
git add docs/post-mortem/YYYY-MM-DD-<feature-stem>-<keyword>.md
git commit -m "docs(post-mortem): root cause for <feature-stem> <keyword>"
# Push the fix branch
git push -u origin fix/<feature-stem>
The system-architect then begins Step 2 on fix/<feature-stem>, reading the post-mortem as input. All subsequent work (stubs, tests, implementation) happens on this branch. It merges to main with --no-ff after acceptance.
Old feature branch: Keep it for reference until the fix branch is merged. Do not delete it prematurely — it contains the history the SA may need to consult.
Before merging a feature branch to main, check if main has diverged since the branch was created.
# Check if main has new commits not in the feature branch
git log feat/<feature-stem>..origin/main --oneline
# If output is non-empty, main has diverged.
# Preview the merge without touching files
git merge-tree $(git merge-base main feat/<feature-stem>) main feat/<feature-stem>
# Empty output = clean merge. Non-empty output = conflicts exist.
If conflicts exist: Resolve them on the feature branch before attempting merge to main.
git checkout feat/<feature-stem>
git merge main # resolve conflicts, commit the merge
git push origin feat/<feature-stem>
Then retry the merge to main.