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

When crafting the commit message description, read ${SKILL_DIR}/references/message-crafting.md for:

• Three description principles (no state words, content over container, don't repeat the prefix)
• Good and bad commit message examples with explanations

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