Git Skills

Semantic Commit Types

Choosing the Right Type

• If it adds something users can see/use → feat
• If it fixes broken behavior → fix
• If it only touches docs/README/comments → docs
• If it changes formatting with no logic change → style
• If it changes structure but not behavior → refactor
• If it only touches test files → test
• Everything else (deps, tooling, config, CI) → chore

Examples

Feature with Scope

feat(net_worth): add account balance history tracking

| Area             | Change                                   |
|------------------|------------------------------------------|
| models.py        | Added BalanceSnapshot frozen dataclass   |
| repository.py    | Added save_snapshot() and get_history()  |
| service.py       | Added compute_balance_trend() function   |
| api/routers/     | Added GET /net-worth/history endpoint    |

Author: Prabhukumar Sivamorthy

Bug Fix with Scope

fix(ingestion): handle empty CSV files without crashing

| Area         | Change                                        |
|--------------|-----------------------------------------------|
| service.py   | Added early return guard for empty DataFrame  |
| test_*.py    | Added regression test for empty file input    |

Author: Prabhukumar Sivamorthy

Refactoring

refactor(payments): extract payment processing into dedicated service

| Area                          | Change                                                |
|-------------------------------|-------------------------------------------------------|
| payments/service.py           | Created PaymentService with process() and refund()    |
| payments/processors.py        | Extracted StripeProcessor and PayPalProcessor          |
| orders/service.py             | Replaced inline payment logic with PaymentService     |
| test_payment_service.py       | Added 15 unit tests for PaymentService                |
| test_order_service.py         | Updated 8 tests to use mocked PaymentService          |

Author: Prabhukumar Sivamorthy

Test-Only Commit

test(budget_goals): add edge case tests for budget limit calculation

| Area                          | Change                                                         |
|-------------------------------|----------------------------------------------------------------|
| test_budget_goals_service.py  | Added 6 tests: zero budget, negative amounts, float precision  |
| conftest.py                   | Added budget_goal_factory fixture                              |

Author: Prabhukumar Sivamorthy

Chore (Dependencies, CI, Config)

chore(deps): upgrade FastAPI to 0.115.0

| Area              | Change                                        |
|-------------------|-----------------------------------------------|
| pyproject.toml    | Bumped fastapi from 0.114.2 to 0.115.0        |
| uv.lock           | Regenerated lock file                         |

Author: Prabhukumar Sivamorthy

Documentation-Only Commit

docs(readme): update README with local development setup

| Area               | Change                                                        |
|--------------------|---------------------------------------------------------------|
| README.md          | Added Prerequisites, Installation, and Running Tests sections |
| docs/architecture.md | Created architecture overview with Mermaid diagram          |

Author: Prabhukumar Sivamorthy

Workflow — Use GitKraken MCP Tools

All git operations MUST use the GitKraken MCP tools. They produce structured, token-efficient output.

Step 1: Sync with remote main

Before any commit or push, always rebase onto the latest origin/main to avoid conflicts and keep history clean.

git fetch origin && git rebase origin/main

If rebase conflicts occur, resolve them before proceeding. After rebasing, use git push --force-with-lease (never --force) to update the remote branch.

Step 2: Check status

mcp__gitkraken__git_status(directory: ".")

Review untracked and modified files. Identify which files to stage.

Step 3: Review recent commits (for style reference)

mcp__gitkraken__git_log_or_diff(directory: ".", action: "log")

Step 4: Review changes

mcp__gitkraken__git_log_or_diff(directory: ".", action: "diff")

Confirm the diff matches intent. Check for secrets or .env files.

Step 5: Stage specific files

mcp__gitkraken__git_add_or_commit(
  directory: ".",
  action: "add",
  files: ["path/to/file1.py", "path/to/file2.py"]
)

Never stage all files blindly. List each file explicitly.

Step 6: Compose and commit

mcp__gitkraken__git_add_or_commit(
  directory: ".",
  action: "commit",
  message: "type(scope): concise description\n\n| Area | Change |\n|---|---|\n| file.py | What changed |\n\nAuthor: Prabhukumar Sivamorthy"
)

Step 7: Verify

mcp__gitkraken__git_log_or_diff(directory: ".", action: "log")

Confirm the commit appears with the correct message format.

Step 8: Push to remote

Always push after committing. Use --force-with-lease after rebasing (Step 1 already ensured the branch is up to date). Do not ask the user — just push.

mcp__gitkraken__git_push(directory: ".")

Creating a Pull Request

When the user asks to create a PR, review all commits on the branch and generate a comprehensive PR description.

Step 1: Identify the base branch

git merge-base origin/main HEAD

Step 2: Review all commits since diverging from main

mcp__gitkraken__git_log_or_diff(directory: ".", action: "log", revision_range: "origin/main..HEAD")

Read every commit message — not just the latest one. Each commit's Area | Change table is your source of truth.

Step 3: Review the full diff

mcp__gitkraken__git_log_or_diff(directory: ".", action: "diff", revision_range: "origin/main..HEAD")

Step 4: Compose the PR description

Build the PR using this template:

## Summary

[2-3 sentences: what this PR does at a high level and why]

## Changes

| Area | Change |
|------|--------|
| [file/module] | [what changed — aggregated from all commits] |
| ... | ... |

## Commits

- `abc1234` type(scope): description
- `def5678` type(scope): description
- ...

## Test Plan

- [ ] Unit tests pass (`uv run pytest src/test/unit/ -q`)
- [ ] [Any specific manual verification steps]
- [ ] No regressions in existing features

Aggregation rules

• Merge related changes — If multiple commits touched the same file, combine them into one row in the Changes table with a summary of the net effect.
• High-level summary first — The Summary section should explain the "why" and overall intent, not list individual commits.
• Preserve commit history — List every commit hash and message in the Commits section so reviewers can trace the history.
• PR title — Derive from the overall theme. If all commits share a scope, use type(scope): high-level description. Keep under 70 characters.

Step 5: Create the PR

gh pr create --title "type(scope): high-level description" --body "..."

Use a HEREDOC for the body to preserve formatting.

Common Mistakes to Avoid

Pre-Commit Verification

Before committing, verify:

• Branch is rebased onto latest origin/main (git fetch origin && git rebase origin/main)
• All staged files are intentional (reviewed via git_log_or_diff diff)
• No secrets or .env files in the staged changes
• Tests pass (uv run pytest src/test/unit/ -q)
• Lint passes (uv run pylint src/budget_analyser)
• Commit message follows the type(scope): description format
• File-change table uses | Area | Change | columns
• Author trailer is Author: Prabhukumar Sivamorthy