efficient-version-control

name	efficient-version-control
description	Use for efficient Git workflows with trunk-based development and short-lived branches. Helps plan changes, commit cleanly, sync safely, open focused PRs, resolve conflicts, and ship with low risk.
argument-hint	What change are you making and what is your branch/PR context?

Efficient Version Control Workflow

What This Skill Produces

• A predictable Git workflow that minimizes merge pain and review delays.
• Clean, reviewable commit history aligned to trunk-based development.
• Safe integration and release readiness checks before merge.

When to Use

• Starting any new coding task or bug fix.
• Preparing commits for review.
• Syncing with latest trunk/main.
• Resolving conflicts and finalizing merge readiness.

Default Assumptions

• Git model: trunk-based development with short-lived branches.
• Branch lifespan target: same day to a few days, not long-running.
• Pull request target: small, focused diff.
• Commit convention: Conventional Commits (feat:, fix:, docs:, chore:, etc.).
• Sync policy default: rebase branch onto latest trunk.
• PR size target: <= 400 changed lines (excluding lock/generated files) when practical.

Workflow

1. Prepare branch and scope.
2. Implement in small validated slices.
3. Commit with intentional history.
4. Sync with trunk early and often.
5. Open a focused PR with evidence.
6. Resolve review feedback efficiently.
7. Final sync and merge readiness checks.

Detailed Procedure

1) Prepare branch and scope

• Pull latest main (or trunk branch) before starting.
• Create a short-lived branch named for purpose (feature/fix/docs/chore).
• Define smallest meaningful deliverable for this branch.

Decision points:

• If change is large, split into multiple sequential branches/PRs.
• If risk is high, isolate behind feature flags or staged rollout strategy.

Completion checks:

• Branch starts from latest trunk.
• Scope statement is clear and bounded.

2) Implement in small validated slices

• Make incremental changes that can be tested independently.
• Run fast local checks after each slice (tests/lint/build relevant to scope).
• Keep unrelated refactors out of the branch unless explicitly planned.

Decision points:

• If a slice fails checks, fix immediately before adding new work.
• If discovering unrelated issues, file follow-up items instead of expanding scope.

Completion checks:

• Each slice builds confidence and keeps branch stable.
• No unrelated churn is mixed into the task.

3) Commit with intentional history

• Group changes by intent (one concern per commit when practical).
• Write commit messages using Conventional Commits and include why/what changed.
• Prefer a history that reviewers can read top-to-bottom logically.

Decision points:

• If history is noisy, squash/fixup locally before opening PR.
• If commits represent meaningful milestones, keep them separate.

Completion checks:

• Commit set is understandable without extra context.
• Messages make root cause and behavior impact clear.
• Commit messages follow Conventional Commits consistently.

4) Sync with trunk early and often

• Rebase onto latest trunk at sensible intervals.
• Resolve conflicts while context is fresh.
• Re-run checks after each sync.

Decision points:

• If repository policy forbids rebase, use merge and document policy exception in PR notes.

Completion checks:

• Branch stays close to trunk.
• Integration conflicts are resolved before review bottlenecks.
• Rebase conflicts are addressed before requesting final review.

5) Open a focused PR with evidence

• Keep PR scope narrow and outcome-oriented.
• Include concise summary, risks, and validation evidence.
• Highlight migration/config/data implications when relevant.

Decision points:

• If PR grows too large, split into stacked or follow-up PRs.
• If behavior changes are subtle, add before/after notes or examples.

Completion checks:

• Reviewer can understand intent, impact, and proof quickly.
• PR has clear test/verification notes.
• PR size stays near target (<= 400 changed lines, excluding lock/generated files) or includes justification when larger.

6) Resolve review feedback efficiently

• Address high-severity and correctness feedback first.
• Keep response commits focused and traceable.
• Clarify design tradeoffs briefly in review discussion.

Decision points:

• If feedback implies scope shift, align with reviewer and re-scope branch.
• If disagreements persist, document options and request maintainer decision.

Completion checks:

• Review threads are resolved with clear outcomes.
• No unresolved blocking feedback remains.

7) Final sync and merge readiness checks

• Sync with latest trunk one final time.
• Confirm CI/local checks pass and critical paths are verified.
• Ensure branch is merge-ready per repository policy.

Completion checks:

• Final branch state is green and up to date.
• Merge can happen without surprise regressions.

Definition Of Done

• Branch remained short-lived and focused.
• Commit history is understandable and intentional.
• PR is small enough for fast, high-quality review.
• Sync and conflict handling happened before merge pressure.
• Validation evidence supports safe integration.