committing-changes

<quick_start>

1. •Review changes: git status, git diff --cached
2. •Stage specific files: git add path/to/file.ts (never git add .)
3. •Write message: type(scope): description (imperative, under 50 chars)
4. •Commit following verification protocol below

</quick_start>

<success_criteria>

A successful commit has:

• •Selective staging (specific files, not git add .)
• •Atomic change (single logical purpose)
• •Conventional Commits format (type, optional scope, imperative description)
• •No debug code or unintended files
• •Clean diff review confirms expected changes only

</success_criteria>

• •Guides selective file staging (never git add .)
• •Writes commit messages in Conventional Commits format
• •Verifies atomic commit principles
• •Adapts commit types to project domain

This skill does NOT:

• •Push commits to remote
• •Create pull requests
• •Modify git configuration
• •Bypass pre-commit hooks

<context_gathering>

Before creating any commit, gather context:

</context_gathering>

<review_workflow_context>

When invoked from a reviewing skill (e.g., reviewing-python, reviewing-typescript):

This skill may be referenced during the commit phase of a code review. In that context:

1. •Committing is the seal of approval — Only commit after verdict is APPROVED
2. •Scope to work item — Stage only files from the approved work item:
   • •Implementation files
   • •Co-located tests (in spx/.../tests/)
   • •Updated outcomes.yaml (test verification ledger)
3. •Include work item reference — Add Refs: {capability}/{feature}/{story} in footer
4. •Verify tests pass — All tests in outcomes.yaml must pass before committing

The reviewing skill provides the specific file list and work item context. This skill provides the commit protocol mechanics.

</review_workflow_context>

<verification_protocol>

Step 1: Selective Staging

# NEVER do this
git add .

# ALWAYS stage specific files
git add path/to/file1.ts path/to/file2.ts

Rules:

• •One logical change per commit
• •Review each ?? untracked file consciously
• •Exclude experimental/incomplete work
• •Use explicit paths, not wildcards

Step 2: Diff Review

git diff --cached           # Review actual changes
git diff --cached --name-only  # Verify file list

Checklist:

• • File count matches scope of change
• • No surprise files included
• • All changes related to single purpose
• • No debug code (console.log, print statements, temp comments)

Step 3: Atomic Commit Verification

• • Single purpose - does exactly one thing
• • Independent - can be reverted without breaking other features
• • Complete - includes everything needed for the change to work

Red Flags - DO NOT COMMIT IF:

• •More than 10 files for a simple fix
• •Changes span unrelated modules
• •Experimental code mixed with stable fixes
• •New unintended files included

</verification_protocol>

<message_format>

<type>[(scope)]: <description>

[optional body]

[optional footer(s)]

Subject Line (Required)

• •Type: Required (see commit_types section)
• •Scope: Optional, component/module name
• •Description: Imperative mood, 50 chars max, no period

feat(auth): add OAuth2 token refresh
fix: handle empty response from API
refactor(db): extract query builder module

Body (Optional)

• •Wrap at 72 characters
• •Explain WHAT and WHY, not HOW
• •Blank line between subject and body

Footer (Optional)

• •BREAKING CHANGE: description - major version bump
• •Refs: #123 or Closes #456 - issue references
• •Work item refs: Refs: feature-32/story-27

</message_format>

<commit_types>

Standard Types

Domain-Specific Types

Projects may define custom types:

Check project's CLAUDE.md or commit-standards.md for custom types.

Avoid

• •chore: - Everything has purpose; use specific type instead

</commit_types>

<breaking_changes>

Mark breaking changes with:

1. •

   Exclamation suffix: "feat!: remove deprecated API"

2. •

   Footer:

   text

   feat: change authentication flow
   
   BREAKING CHANGE: JWT tokens now expire in 1 hour instead of 24
   

</breaking_changes>

<scope_guidelines>

Use Scope When:

• •Component-specific: feat(auth): add 2FA support
• •Module changes: fix(api): handle rate limiting
• •Clear subsystem: test(db): add connection pool tests

Omit Scope When:

• •Single-file change: fix: correct typo in error message
• •Cross-cutting: refactor: consolidate error handling
• •Obvious context: docs: update installation guide

</scope_guidelines>

<description_guidelines>

Write for the reader, not the writer.

Someone scanning git log --oneline needs to understand what changed without opening the commit.

Principle 1: No State Words

Describe the action, not the prior problem:

# ❌ Describes prior state
fix: handle missing config file
spec(auth): add missing validation rules

# ✅ Describes the action
fix: return defaults when config absent
spec(auth): specify validation rules

Avoid: "missing", "broken", "wrong", "bad", "incorrect"

Principle 2: Content Over Container

Describe WHAT changed, not WHICH files:

# ❌ Describes the container
spec(session): add stories for timeout feature
docs: update README file

# ✅ Describes the content
spec(session): specify timeout and cleanup behaviors
docs: add installation prerequisites

Principle 3: Don't Repeat the Prefix

The type already tells you what kind of change:

# ❌ Redundant - prefix already says it's a spec
spec(session): add session management spec
spec(auth): define auth feature stories

# ✅ Just describe the content
spec(session): specify timeout and cleanup behaviors
spec(auth): specify OAuth2 token lifecycle

</description_guidelines>

Good Examples

feat(parser): add support for nested expressions

Enables users to write complex queries with unlimited nesting depth.
Previously limited to 3 levels.

Refs: #234

fix: prevent crash on empty config file

Return sensible defaults when config is missing or empty
instead of throwing unhandled exception.

refactor: extract validation logic into separate module

Prepares codebase for unit testing by isolating validation
from business logic.

Bad Examples

# Too vague
fix: bug fixes

# Multiple unrelated changes
feat: add parser and fix tests and update docs

# Contains attribution (NEVER do this)
feat: add export feature (by John)

# Not atomic
refactor: various improvements

# Describes prior state instead of action
fix: handle missing config
spec(auth): add missing validation

# Describes container instead of content
spec(session): add stories for advanced operations
docs: update README file

# Repeats the prefix
spec(session): add session spec
test(auth): add auth tests

<decision_tree>

Is this a new user feature?           → feat:
Is this fixing a bug?                 → fix:
Is this improving performance?        → perf:
Is this code reorganization?          → refactor:
Is this build/dependencies?           → build:
Is this CI/CD?                        → ci:
Is this documentation?                → docs:
Is this adding/changing tests?        → test:
Is this context/workflow docs?        → ctx: (if project uses it)

</decision_tree>

<critical_rules>

1. •NO ATTRIBUTION - Never include author names in commit messages
2. •IMPERATIVE MOOD - "add feature" not "added feature" or "adds feature"
3. •NO PERIOD - Subject line doesn't end with punctuation
4. •SELECTIVE STAGING - Never use git add .
5. •ATOMIC COMMITS - One logical change per commit

</critical_rules>

<commands_reference>

# Check what will be committed
git status
git diff --cached
git diff --cached --name-only

# Stage selectively
git add path/to/specific/file.ts

# Commit with multi-line message
git commit -m "$(cat <<'EOF'
feat(scope): subject line here

Body explaining why this change was made.
Wrapped at 72 characters for readability.

Refs: #123
EOF
)"

# View recent commits for style reference
git log --oneline -10

</commands_reference>