playbooks

home / skills / 89jobrien / steve / git-workflow

git-workflow skill

/steve/skills/git-workflow

This skill helps you design and manage Git workflows, PR templates, and branch strategies to improve code reviews and collaboration.

npx playbooks add skill 89jobrien/steve --skill git-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.4 KB
---
name: git-workflow
description: Git workflow and pull request specialist. Use when creating PRs, managing
  branches, establishing git conventions, or improving code review processes.
author: Joseph OBrien
status: unpublished
updated: '2025-12-23'
version: 1.0.1
tag: skill
type: skill
---

# Git Workflow Skill

Expert guidance for git workflows, pull request best practices, branch management, and code review processes.

## What This Skill Does

- Creates well-structured pull requests
- Establishes branch naming conventions
- Defines PR templates and checklists
- Reviews PR quality
- Manages merge strategies
- Handles rebasing and conflict resolution

## When to Use

- Creating pull requests
- Establishing team git conventions
- Improving code review process
- Branch strategy decisions
- PR template creation

## Reference Files

- `references/PULL_REQUEST.template.md` - PR body templates for features, bugs, refactors

## Branch Naming

```
<type>/<issue-number>-<short-description>
```

Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`

## PR Best Practices

1. Clear title following conventional format
2. Summary explaining WHAT and WHY
3. Specific test plan
4. Breaking changes documented
5. Screenshots for UI changes
6. Link to related issues

## Merge Strategies

| Strategy | When to Use |
|----------|-------------|
| Squash | Feature branches, clean history |
| Merge | Preserve commits, audit trail |
| Rebase | Linear history, small changes |

Overview

This skill is a git workflow and pull request specialist that helps teams create better PRs, manage branches, and improve code review processes. It provides practical conventions for branch naming, PR structure, merge strategies, and conflict handling. Use it to standardize workflows and reduce friction during collaboration.

How this skill works

The skill inspects the intended change and recommends a branch name using a consistent pattern, generates a clear PR title and body following a template, and suggests a test plan and checklist. It evaluates PR quality against best-practice criteria (scope, summary, tests, breaking changes) and recommends an appropriate merge strategy. It can also walk through rebasing steps and practical conflict resolution tips.

When to use it

  • When creating a new feature, bugfix, or refactor branch and preparing a pull request
  • When defining or updating team branch naming and PR conventions
  • When improving code review quality and reviewer guidance
  • When choosing a merge strategy for releases or feature integration
  • When resolving rebases and merge conflicts before merging

Best practices

  • Name branches as <type>/<issue-number>-<short-description> using types like feat, fix, refactor, docs, test, chore
  • Write PR titles and bodies that state WHAT changed and WHY, include a concise test plan and links to related issues
  • Include breaking-change notes and screenshots for UI work, and document migration steps if needed
  • Prefer squash merges for tidy history, merge commits to preserve full audit trails, and rebase for a linear timeline on small changes
  • Use a checklist in every PR for tests, linting, docs, and any environment setup required for reviewers

Example use cases

  • Generate a PR body for a new feature with a test plan and related issue links
  • Define a branch naming policy for a growing cross-functional team
  • Review an incoming PR and flag missing tests, unclear scope, or undocumented breaking changes
  • Recommend squash vs. merge vs. rebase for a release branch
  • Guide a developer through resolving a rebase conflict step-by-step

FAQ

Which merge strategy should I pick for features?

Use squash to keep commit history concise for feature branches; choose merge commits when you need a complete history or an audit trail.

How should I format branch names for bug fixes?

Use fix/<issue-number>-short-description, keeping the short description lowercased, hyphen-separated, and under 50 characters.