Committing Changes

1. Run project validation first: Check CLAUDE.md for just check, pnpm run check, etc.
2. Review changes: git status, git diff
3. Classify changes by concern — group by type+scope, split if multiple groups
4. Stage specific files for ONE concern: git add path/to/file.ts (never git add .)
5. Write message: type(scope): description (imperative, under 50 chars)
6. Commit, then repeat from step 4 for remaining concerns

A successful commit has:

• Concerns classified before staging (type+scope grouping applied)
• One concern per commit (split when types or scopes differ)
• Selective staging (specific files, not git add .)
• Conventional Commits format (type, optional scope, imperative description)
• No debug code or unintended files
• Clean diff review confirms expected changes only

• 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

Before creating any commit, gather 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/)
3. Include work item reference — Add Refs: {capability}/{feature}/{story} in footer
4. Verify tests pass — All tests must pass before committing

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

MANDATORY: Analyze before staging. Never stage everything then ask about splitting.

After gathering context (git status, git diff), classify every changed and untracked file by concern before touching git add. A concern is one logical purpose that gets one commit type and one scope.

Classification procedure:

1. List every changed/untracked file.
2. Assign each file a commit type (spec, feat, fix, refactor, docs, etc.).
3. Assign each file a scope (module, plugin, component).
4. Group files that share the same type AND scope — each group is one commit.

Split signals — if ANY of these are true, you MUST split into multiple commits:

• Files need different commit types (e.g., spec for a design doc + feat for implementation)
• Files belong to different scopes (e.g., methodology/ spec + plugins/ code)
• Changes serve different purposes even within the same directory
• A design/spec document and its implementation are both present

Commit ordering:

When splitting, commit in dependency order:

1. Specs and design documents first (they define what follows)
2. Infrastructure and enablers second
3. Implementation last
4. Tests alongside whatever they test

Example:

Changed files:
  methodology/skills/skill-structure.md   → spec(spec-tree)
  plugins/spec-tree/**                     → feat(spec-tree)

→ Two commits:
  1. spec(spec-tree): define methodology
  2. feat(spec-tree): add plugin implementation

Never ask the user whether to split. Apply the classification procedure. If the result is multiple groups, commit them separately. Separation of concerns is not a preference — it is a requirement.

Step 0: Run Project-Specific Validation (BEFORE Staging)

Before staging any files, check CLAUDE.md for project-specific validation commands and run them. This prevents having to re-stage after auto-fixes.

# Check CLAUDE.md for commands like:
just check        # Justfile task runner
just validate
pnpm run check    # pnpm scripts
pnpm run validate
npm run check     # npm scripts
make check        # Makefile targets
make lint

Why before staging? Many project commands (formatters, linters with auto-fix) modify files. Running them after staging means you need to re-stage the fixed files. Run validation first, then stage.

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

<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

Standard Types

Domain-Specific Types

Projects may define custom types:

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

IMPORTANT: NEVER USE chore:. Everything has purpose; use specific type instead

Mark breaking changes with:

1. Exclamation suffix: "feat!: remove deprecated API"

2. Footer:

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

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

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

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

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)

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

# 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