---
name: jamestorrevillas/git-workflow
source: https://app.decimal.ai/s/jamestorrevillas-git-workflow@1/SKILL.md
source_sha256: 0bfa948434c4
---

# Git Workflow

## Commit Message Convention

Follow the **Conventional Commits** specification. This enables automated versioning, changelogs, and semantic releases.

### Format
```
type(scope): short description

[optional body — explain the WHY, not the WHAT]

[optional footer — breaking changes, issue refs]
```

### Types
| Type | When to Use |
|---|---|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or updating tests |
| `docs` | Documentation only |
| `chore` | Build process, dependency updates, tooling |
| `ci` | CI/CD configuration changes |
| `style` | Formatting, whitespace (no logic change) |
| `revert` | Reverting a previous commit |

### Examples
```
feat(auth): add OAuth2 login with Google

fix(api): handle null response from payment gateway

refactor(db): extract query builder into separate module

docs(readme): update local setup instructions

chore(deps): upgrade dependencies to latest versions
```

### Rules
- Subject line: max 72 characters, imperative mood ("add" not "added")
- Body: explain WHY the change was made, not what (the diff shows what)
- Reference issue/ticket IDs in footer: `Closes #123` or `Refs US-2111704`
- If AI-assisted, note it: `Co-authored-by: GitHub Copilot`

---

## PR Description Template

Every PR should answer three questions:

```markdown
## What
Brief summary of what changed.

## Why
The business or technical reason for this change.

## How
Key implementation decisions or approach taken.

## Testing
How was this verified? (unit tests, manual testing, E2E)

## Checklist
- [ ] Tests added/updated
- [ ] No new security vulnerabilities introduced
- [ ] Documentation updated if needed
- [ ] No breaking changes (or documented if there are)
```

---

## Branching Strategy

### GitHub Flow (Recommended for most teams)
```
main
└── feature/US-1234-short-description
└── fix/bug-short-description
└── chore/update-dependencies
```
- Branch from `main`, merge back to `main` via PR
- Deploy from `main` continuously

### Git Flow (For versioned releases)
```
main          ← production
develop       ← integration
└── feature/* ← new features
└── release/* ← release prep
└── hotfix/*  ← urgent production fixes
```

### Branch Naming Convention
```
type/ticket-id-short-description

Examples:
feat/US-2111704-query-clarity-agent
fix/US-2098686-btt-ui-button-alignment
chore/update-langchain-dependencies
```

---

## Code Review Etiquette

### Feedback Categories
Tag all review comments to set expectations:

| Tag | Meaning |
|---|---|
| `BLOCKER` | Must be fixed before merge. Breaks functionality or violates standards. |
| `WARNING` | Should be fixed. Technical debt or potential issue. |
| `SUGGESTION` | Optional improvement. Worth considering but not required. |
| `QUESTION` | Asking for clarification, not requesting a change. |
| `NITPICK` | Minor style or preference. Author can decide. |

### Reviewer Mindset
- Review the code, not the person
- Explain the reason behind every BLOCKER or WARNING
- Acknowledge good work — not just problems
- Ask questions before assuming intent: "What was the reason for this approach?"
- Focus on architecture and logic issues first, style issues last (that's what linters are for)

### Author Mindset
- Keep PRs small and focused — one concern per PR
- Respond to every comment, even if just acknowledging
- Mark resolved conversations as resolved
- Don't merge until all BLOCKERs are addressed

---

## Changelog Generation

When generating a changelog from commits, group by type:

```markdown
## [1.2.0] - 2026-03-20

### Features
- feat(auth): add OAuth2 login with Google (#45)

### Bug Fixes
- fix(api): handle null response from payment gateway (#46)

### Performance
- perf(db): optimize query for large datasets (#47)
```

---

## AI Attribution in Commits

When code was AI-assisted, be transparent in the commit:
```
feat(api): generate REST endpoint scaffolding

Scaffolded with GitHub Copilot, reviewed and modified by developer.
Co-authored-by: GitHub Copilot <copilot@github.com>
```