git-collaboration-workflow

name	git-collaboration-workflow
description	Use when planning branch strategy, making commits, reviewing diffs, resolving conflicts, preparing pull requests, or shipping releases. Covers trunk-friendly collaboration, commit hygiene, conflict recovery, and CI-linked release discipline.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

Git Collaboration Workflow

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Use when planning branch strategy, making commits, reviewing diffs, resolving conflicts, preparing pull requests, or shipping releases. Covers trunk-friendly collaboration, commit hygiene, conflict recovery, and CI-linked release discipline.

Required Inputs

Artefact	Required?	Purpose
Repository status and current branch	yes	Establish integration state
Intended scope and release target	yes	Bound commits and review

References

• Use the references/ directory for deep detail after reading the core workflow below.

Use this skill to keep version control readable, reviewable, and recoverable. It is for disciplined delivery, not command memorization.

Working Rules

• Keep main or the release branch deployable.
• Prefer small branches and small review units.
• Prefer trunk-based integration or similarly short-lived branches.
• Review your own diff before asking others to review it.
• Use recovery-first thinking before destructive commands.
• Treat commit history as shared operational documentation.
• Treat broken builds as stop-the-line events for the affected team.

Collaboration Workflow

1. Start Clean

Before coding:

• Confirm branch and upstream state.
• Inspect working tree changes.
• Separate unrelated work before starting.

2. Change in Reviewable Slices

Aim for commits that answer one question:

• What changed?
• Why now?
• What risk does it carry?

If one commit needs a long explanation to prove it is safe, split it.

3. Stage Intentionally

• Stage only files relevant to the current intent.
• Avoid "everything changed" commits unless it is truly mechanical and isolated.
• Re-read staged diffs before committing.

4. Write Useful Commits

Good commit messages state intent and scope:

• feat: add invoice aging query for finance dashboard
• fix: prevent duplicate webhook processing on retry
• refactor: extract permission resolver from order service

Avoid messages that only describe mechanics.

5. Integrate Early

• Rebase or merge from the base branch before divergence becomes expensive.
• Resolve conflicts with semantic understanding, not blind marker deletion.
• Re-run tests after integration, not only before it.

6. Review and Release

• PRs should explain impact, risk, and verification.
• Reviewers should focus on bugs, regressions, migration risk, and missing tests.
• Releases should include rollback awareness and post-deploy verification.
• Keep branch strategy coupled to CI quality and release safety, not personal preference.
• Use feature flags or other release controls to keep integration small when exposure needs to wait.

Decision Heuristics

Use rebase when:

• You want a clean linear feature history before merge.
• The branch is private or team conventions allow rewriting it.

Use merge when:

• Preserving integration history is useful.
• The branch is shared broadly and rewriting would create confusion.

Use revert before reset when:

• The bad change is already shared.
• You need an auditable undo in team history.

Require extra release notes when:

• schema or migration changes are present
• permissions, billing, or critical workflows changed
• rollout needs feature flags, canaries, or manual checks

Conflict Resolution Checklist

• Identify which side changed behavior and why.
• Reconstruct the intended end state.
• Re-run tests around the conflicting area.
• Re-check generated files, lock files, schema changes, and config files.
• Confirm no logic was silently dropped during resolution.

Branch and Release Standards

• Keep main releasable or one step from releasable.
• Pair risky changes with migration notes, verification notes, and rollback notes in the PR.
• Do not merge changes that require tribal knowledge to deploy safely.
• If CI is red for the branch strategy, the workflow is broken no matter how clean the history looks.

See references/review-and-release.md for PR and release checklists.

Anti-Patterns

• Long-lived branches with hidden divergence.
• Mixed refactor-plus-feature-plus-formatting commits.
• Force pushes without team awareness on shared branches.
• Destructive recovery without first inspecting reflog-friendly options.
• PRs that ship without migration, rollback, or verification notes when needed.
• Treating Git workflow as separate from release engineering and CI health.

References

• references/review-and-release.md: Pull request, merge, and release checklists.
• references/trunk-based-delivery.md: Short-lived branch and integration rules.
• ../world-class-engineering/references/source-patterns.md: Git workflows derived from the supplied PDFs.

Degraded Mode

If Git execution is unavailable, provide non-destructive commands and expected checks; do not claim commit, push, merge, or release success.

Outputs

• Produce a scoped branch/commit/merge workflow with review evidence, conflict handling, and repository-safe commands.

Workflow

Inspect status and diff, isolate scope, validate changes, commit intentionally, push only when requested, and report unresolved conflicts or checks.

Capability contract

Read-only Git inspection is allowed by default. Commit, push, merge, rebase, force-update, or branch deletion requires explicit workflow authority and protected-branch awareness.