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

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.