Ref sp dev git commits

Git Commits

Purpose

Define how a repository groups changes into focused commits and how commit messages should be written. The defaults below are portable; the concrete scopes and examples are this repo's instantiation.

When to use this skill

• The user asks how changes should be committed.
• You need to write a commit title or body.
• You need to decide whether one change set should become one commit or several.
• The work came from an automated command and the commit message needs reproducibility details.

Scope boundaries

This skill owns the rules: how changes are grouped into commits, and how a commit title and body are written.

• tool-sp-commit — applying those rules to a real working diff. Read this skill for the rules; invoke that one to group and write the actual commits.
• ref-sp-py-commitizen — the release tooling that consumes conventional-commit types: cz bump, version providers, generated changelogs.
• ref-sp-dev-semantic-versioning — what a bump level means. A commit's type feeds a future bump; choosing the bump is not this skill's job.
• ref-sp-dev-docs-authoring — project documentation. A commit body explains one change to a reviewer; it is not a doc.

Core Rules

• Keep each commit focused on one logical change.
• Validate the relevant slice before committing whenever a focused check exists.
• Use non-interactive commit flows.
• Keep unrelated user changes out of your commit.

Commit Title Format

Use this default title format:

type(scope): Short description of the commit

Defaults:

• Use one of feat, fix, docs, or chore as the type.
• Treat skill files as documentation. When a commit only changes skill guidance or other docs-only content, prefer docs(...) over feat(...) or chore(...).
• Always include a short scope that names the main surface, such as skills, policy, scripts, docs, or commits.
• For changes to commit-related skill docs such as ref-sp-dev-git-commits or tool-sp-commit, prefer the scope commit-skills, for example docs(commit-skills): Short description of the commit.
• Keep the short description concise, specific, and easy to scan in git log.
• Prefer one clear outcome over a list of implementation details.

Commit Body Rules

• Add a long description when the commit is not trivial.
• Use the body to explain the key details and why the change exists, not to restate the title.
• Separate the title and body with a blank line.
• Record change provenance in the body when the change came from something other than hand-editing. This is most relevant for automated changes such as a codemod, link fixer, formatter, or generator: include the command that produced the change so another engineer can rerun or audit it.
• Redact personal or private details from a recorded command before committing it. Replace absolute home paths with a repo-relative or generic path, drop the username, and never include tokens, secrets, or machine-specific identifiers. Record the reproducible command shape, not your local environment.
• Very mundane commits such as a straightforward lint fix do not need a long description.

Task Framing

Command or action	What	Why	When	Expected outcome
Choose commit boundaries	Decide which changed files belong together.	Focused commits are easier to review, revert, and explain.	Before staging or writing the message.	Each commit has one coherent purpose.
Write the title	Summarize the change in type(scope): Short description of the commit form.	The title is the main line readers see in history and reviews.	For every commit.	The title makes the commit easy to categorize and skim.
Add a body	Explain the key details and why.	Non-trivial commits need context that the title cannot carry alone.	When the commit changes behavior, introduces structure, or would be unclear from the title alone.	The commit explains the important reasoning without becoming a changelog dump.
Record change provenance	Include the command that produced the change, with personal or private details redacted.	Reproducibility matters when the work came from automation, and the body should not leak local paths or credentials.	When a codemod, link fixer, generator, migration command, formatter, or bulk rewrite produced the changes.	Another engineer can rerun or audit the automation without seeing machine-specific or private data.

Examples

docs(skills): Add tool-sp-create-skill guidance

- add a guided intake flow for creating new skills
- route naming decisions through ref-sp-agents-skills-authoring
- keep the initial scaffold narrow to fit progressive disclosure

Why:
- reduce repeated manual setup when adding new skills

docs(commit-skills): Clarify commit message defaults for skill docs

chore(commits): Record codemod-generated import cleanup

- normalize import ordering across the new ref-skill package names

Why:
- keep the rename follow-up deterministic and reproducible

Command:
- uv run python -m scripts.some_codemod --rewrite-imports ./src

The Command: line records the reproducible command shape. Redact private details first: use a repo-relative path such as ./src rather than an absolute /home/<user>/... path, drop the username, and never include tokens or secrets.

chore(formatting): Fix lint formatting

Validation

• Confirm the title fits the default type(scope): Short description of the commit format.
• Confirm the body exists when the commit would otherwise be unclear.
• Confirm automated changes include the generating command with private details redacted.
• Confirm the message matches the actual staged diff, not the whole working tree.