romanescu11/hermes-skill-factory/git-pr-workflow

Git PR Workflow

A repeatable, disciplined workflow for turning work-in-progress code into a clean pull request ready for review. Covers branch hygiene, commit quality, and PR description best practices.

When to Activate

Activate this skill when:

• You've finished a feature or fix and are ready to open a PR
• You need to prepare a branch for code review
• You want to ensure your PR passes CI before review

Workflow

Phase 1: Branch & Commit Hygiene

Clean up the branch before opening the PR.

Steps:

1. Run git status to confirm working tree is clean
2. Run git log origin/main..HEAD --oneline to review commits
3. Squash or reword any "WIP", "fix typo", or noise commits with git rebase -i origin/main
4. Ensure each commit has a clear imperative message: Add user auth, not added stuff
5. Run git diff origin/main for a final sanity check

Before moving on:

• [ ] No WIP commits remain
• [ ] All commits have clear messages
• [ ] No unintended files are staged

Phase 2: CI Pre-flight

Run tests locally before pushing.

Steps:

1. Run the test suite: pytest / npm test / project-specific command
2. Run the linter: ruff check . / eslint . / equivalent
3. Fix any failures — do NOT push a red branch
4. Push the branch: git push -u origin HEAD

Before moving on:

• [ ] All tests pass locally
• [ ] Linter reports no errors

Phase 3: PR Description

Open the PR with a description that makes reviewers' lives easy.

Steps:

1. Open the PR on GitHub / GitLab
2. Title: imperative mood, under 60 chars — Add OAuth2 login flow
3. Body: use this structure:

``` ## What [1-3 bullets: what changed]

## Why [Context: issue link, ticket, or motivation]

## How to Test [Checklist of manual test steps]

## Screenshots (if UI change) ```

1. Link to any related issues: Closes #123
2. Assign reviewers and labels

Before moving on:

• [ ] PR title follows convention
• [ ] Description has What / Why / How to Test
• [ ] Reviewers assigned

Quality Checklist

• [ ] Branch is rebased on top of main
• [ ] No merge conflicts
• [ ] CI is green after push
• [ ] PR description complete
• [ ] Self-reviewed the diff one more time

Examples

Example 1: Feature PR

Working on a new login page. After finishing:

1. git rebase -i origin/main → squash 4 commits into 1: Add OAuth2 login page
2. pytest → all pass
3. git push -u origin feature/oauth-login
4. Open PR: title Add OAuth2 login page, link to issue #88
5. Assign 2 reviewers, add label feature

Example 2: Bug Fix PR

Fixed a null pointer in the payment service:

1. Single commit already clean: Fix null pointer in PaymentService.charge
2. npm test → passes
3. git push, open PR titled Fix null pointer in PaymentService
4. Body explains the root cause and how to reproduce before the fix

Anti-patterns

• ❌ Opening a PR from main directly
• ❌ Pushing without running tests first
• ❌ PR descriptions that just say "fixes bug"
• ❌ 47-commit PRs with no squashing
• ❌ Assigning reviewers before CI is green

Integration

This skill works well with:

• software-development/code-review — for what reviewers will check
• software-development/systematic-debugging — if CI fails after push

_Generated by Skill Factory — example output_