Use when planning commit strategies or determining when to commit changes. Helps developers commit early and often to tell the story of their development process.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
name: git-storytelling-commit-strategy description: Use when planning commit strategies or determining when to commit changes. Helps developers commit early and often to tell the story of their development process. allowed-tools:
This skill helps you understand and implement effective commit strategies that tell the story of your development process through small, focused commits.
The practice of making small, frequent commits throughout development rather than large, infrequent commits. This approach:
Each commit should represent a single logical change:
This makes the git history navigable and meaningful.
Your commits should read like a story:
✅ You've completed a logical unit of work (even if small) ✅ Tests pass for the changes made ✅ You're about to switch tasks or take a break ✅ You've refactored code to be clearer ✅ You've fixed a bug (one commit per bug) ✅ You've added a new file or module ✅ You've updated documentation ✅ You're at a stable checkpoint
❌ Code doesn't compile or has syntax errors ❌ Tests are failing (unless documenting a known issue) ❌ You have unrelated changes mixed together ❌ You have debugging code or temporary comments ❌ You have secrets or sensitive data
feat: add user authentication with JWT
Implement JWT-based authentication system with:
- Login endpoint
- Token generation
- Token validation middleware
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
fix: resolve memory leak in websocket handler
Close websocket connections properly when client disconnects
to prevent memory accumulation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
refactor: extract validation logic into separate module
Move validation functions from controllers to validators/
for better reusability and testing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
feat: - New featurefix: - Bug fixrefactor: - Code restructuring without behavior changetest: - Adding or updating testsdocs: - Documentation changesstyle: - Formatting, whitespace changesperf: - Performance improvementschore: - Maintenance tasksGood storytelling commits:
# 1. Setup
git commit -m "feat: initialize Express server with basic configuration"
# 2. Foundation
git commit -m "feat: add database connection with Prisma"
# 3. Feature development
git commit -m "feat: create user model and migration"
git commit -m "feat: add user registration endpoint"
git commit -m "feat: add user login endpoint"
git commit -m "test: add user authentication tests"
# 4. Refinement
git commit -m "fix: validate email format in registration"
git commit -m "refactor: extract password hashing to utility"
# 5. Documentation
git commit -m "docs: add API endpoint documentation"
# 1. Identify and reproduce
git commit -m "test: add failing test for pagination edge case"
# 2. Fix the issue
git commit -m "fix: handle empty results in pagination"
# 3. Verify
git commit -m "test: verify pagination works with edge cases"
# 4. Cleanup
git commit -m "refactor: simplify pagination logic"
# 1. Prepare
git commit -m "test: add comprehensive tests before refactoring"
# 2. Small steps
git commit -m "refactor: extract common validation logic"
git commit -m "refactor: rename confusing variable names"
git commit -m "refactor: split large function into smaller units"
# 3. Verify
git commit -m "test: verify all tests still pass after refactor"
❌ The Dump Truck
git commit -m "updated files" # Too vague, too many changes
❌ The Novel
git commit -m "fixed bug and added feature and updated docs and refactored code and..."
❌ The WIP Spam
git commit -m "wip"
git commit -m "wip2"
git commit -m "wip3"
# Use better descriptions even for work-in-progress
❌ The Time Machine
# Making 50 commits then squashing them ALL into one
# This destroys the development story entirely
✅ Better Approach: Clean up meaningless commits locally before pushing, but preserve the logical story:
# Keep logical commits that tell the story
git rebase -i origin/main
# Result: Clean story with meaningful commits
# feat: implement user authentication
# test: add authentication tests
# fix: handle edge cases
# docs: document authentication API
# On feature branch
git checkout -b feature/user-auth
# Make small commits
git commit -m "feat: add User model"
git commit -m "feat: add authentication middleware"
git commit -m "test: add auth tests"
# Clean history is preserved when merging
git checkout main
git merge feature/user-auth
Small commits make code review easier:
Frequent commits trigger CI more often:
✅ Safe to rebase: Local commits (not yet pushed)
❌ Dangerous to rebase: Pushed commits (already on remote)
Before pushing your work, consider cleaning up if you have:
Use git rebase -i to clean up your local commit history before pushing:
# Check what commits you haven't pushed yet
git log origin/main..HEAD --oneline
# Interactive rebase for last 5 commits
git rebase -i HEAD~5
# Or rebase everything since branching from main
git rebase -i origin/main
In the interactive rebase editor, you can:
pick - Keep commit as-isreword - Keep commit but edit messageedit - Pause to amend the commitsquash - Merge into previous commit, keep both messagesfixup - Merge into previous commit, discard this messagedrop - Remove commit entirelyreorder - Move lines to reorder commitsPattern 1: Squash fixup commits
Before:
feat: add user authentication
wip: add tests
fix: oops forgot import
fix: typo in test
test: add more edge cases
After rebasing:
feat: add user authentication
test: add authentication tests
Commands in rebase editor:
pick abc123 feat: add user authentication
pick def456 wip: add tests
fixup ghi789 fix: oops forgot import
fixup jkl012 fix: typo in test
squash mno345 test: add more edge cases
Pattern 2: Split WIP into logical commits
Before:
wip: stuff
wip: more stuff
wip: final changes
After rebasing:
feat: implement user authentication
test: add authentication tests
docs: document auth API
Commands in rebase editor:
edit abc123 wip: stuff
edit def456 wip: more stuff
edit ghi789 wip: final changes
Then for each commit:
git reset HEAD^ # Unstage the commit
git add -p # Selectively stage changes
git commit -m "feat: implement user authentication"
git add -p # Stage more changes
git commit -m "test: add authentication tests"
# ... etc
git rebase --continue
Pattern 3: Improve commit messages
Before:
stuff
more changes
final
After rebasing:
feat: add JWT authentication
test: add authentication tests
docs: update API documentation
Commands in rebase editor:
reword abc123 stuff
reword def456 more changes
reword ghi789 final
# During development - commit frequently
git commit -m "wip: start auth implementation"
git commit -m "wip: add JWT generation"
git commit -m "oops: fix import"
git commit -m "wip: add tests"
git commit -m "fix: test typo"
git commit -m "wip: add validation"
# Before pushing - check what you have
git log origin/main..HEAD --oneline
# Shows 6 messy WIP commits
# Clean up with interactive rebase
git rebase -i origin/main
# In editor, consolidate into logical commits:
# - Squash the "oops" and "fix" commits
# - Combine related WIP commits
# - Reword commit messages to be descriptive
# Result: Clean, logical history
git log origin/main..HEAD --oneline
#
# feat: implement JWT authentication
# test: add authentication tests
# feat: add request validation
# Now push your clean history
git push origin feature/user-auth
Don't rebase if:
If a rebase goes wrong:
# Abort ongoing rebase
git rebase --abort
# Or recover using reflog (rebase already completed)
git reflog # Find the commit before rebase
git reset --hard HEAD@{5} # Go back to that state
git log to see what you're about to pushgit diff to review changesgit rebase -i to polish local commits before sharingReview your commits to ensure they tell a good story:
# View commit history
git log --oneline --graph
# See what changed in each commit
git log -p
# Review recent commits
git log --oneline -10
A good story should be: