Commit

Commit workflow that ensures quality gates pass and changelog is updated before committing.

When to Use

• After /code-review passes with no critical issues
• When asked to commit, save, or wrap up work
• Before creating a PR

Workflow

┌─────────────────────┐
│ 1. Run quality      │
│    checks           │
│    ty → ruff → pytest
└─────────┬───────────┘
          │
          ▼
    ┌─────────────┐
    │ All pass?   │───No──→ STOP. Fix issues first.
    └─────┬───────┘
          │Yes
          ▼
┌─────────────────────┐
│ 2. Update CHANGELOG │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 3. Stage + Commit   │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 4. Verify success   │
└─────────────────────┘

Step 1: Run Quality Checks

Run in this order. Stop on first failure.

ty                    # Type checking
ruff check .          # Linting
ruff format --check . # Format check
pytest                # Tests

If any fail: Fix the issue. Do not proceed to commit.

No exceptions:

• “It’s a flaky test” → Fix the test or mark it properly
• “I manually tested it” → Automated tests must pass
• “We can fix it later” → Later never comes. Fix now.

Step 2: Update CHANGELOG

Create or update CHANGELOG.md in project root.

Format:

# Changelog

## [Unreleased]

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

### Removed
- Removed feature description

Rules:

• Add entry under [Unreleased] section
• Use appropriate category (Added/Changed/Fixed/Removed)
• Be concise but specific – what changed and why it matters
• If CHANGELOG.md doesn’t exist, create it

Step 3: Stage and Commit

git add -A  # Or specific files if preferred
git commit -m "$(cat <<'EOF'
Short summary in imperative mood (max 50 chars)

Longer description if needed. Explain what changed and why.
Keep lines under 72 characters.

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Commit message guidelines:

• First line: imperative mood, max 50 chars (“Add feature” not “Added feature”)
• Blank line after summary
• Body: explain what and why, not how
• Reference issues if applicable

Step 4: Verify Success

git status  # Should show clean working tree
git log -1  # Verify commit message looks correct

Red Flags – STOP

• Tests failing → Fix before commit
• Linting errors → Fix before commit
• Type errors → Fix before commit
• No changelog entry → Add one
• Vague commit message → Rewrite it

Common Mistakes