Commit

Commit

Overview

Use this skill when a user asks for a commit or asks how a commit should be written for Pocodex. The goal is to produce a clean, policy-compliant git commit that matches the actual diff and works with release-please.

Workflow

1. Inspect the worktree with git status --short and git diff --stat, then read the diff for the files that are actually part of the requested change.
2. Exclude unrelated user changes. Do not stage or commit files outside the requested scope.
3. Run pnpm run check:commit before committing. If it fails, fix the issues or report the blocker instead of committing a broken tree.
4. Stage only the intended files with git add <path>....
5. Write a Conventional Commit message that accurately describes the staged diff.
6. Commit with git commit. Prefer a single -m subject for small changes, or add a body when the why matters.

Commit Rules

• Use Conventional Commits because release-please derives release notes and version bumps from merged commit history.
• Preferred types in this repo: feat, fix, refactor, docs, test, build, ci, chore.
• Use an optional scope when it improves clarity, for example feat(server): ... or fix(bootstrap): ....
• Use the imperative mood in the subject line.
• Keep the subject specific to the staged diff. Do not write broad summaries that cover unstaged work.
• Mark breaking changes with ! in the header and include a BREAKING CHANGE: footer in the body.
• Avoid placeholder types such as update, misc, or changes.

Message Shape

Use this shape:

type(scope): short summary

Optional explanatory body.

BREAKING CHANGE: required when behavior or API compatibility changes.

Choosing The Type

• feat: user-visible behavior or capability added
• fix: bug fix or regression fix
• refactor: internal restructuring without intended behavior change
• docs: README, CONTRIBUTING, skills, or other documentation-only changes
• test: test-only changes
• build: packaging, dependencies, or build tooling
• ci: GitHub Actions or other automation pipeline changes
• chore: maintenance that does not fit the above and should not usually trigger a release note highlight

Examples

• feat: add LAN URL fallback for remote browser sessions
• fix(server): ignore malformed ipc payloads
• build: add release-please automation
• docs(commit): document conventional commit policy
• refactor(app-server-bridge): inline typed event overloads

Guardrails

• Do not commit unrelated local edits just because they are present in the worktree.
• Do not bypass the commit-msg or pre-commit hooks unless the user explicitly asks.
• If the diff contains multiple unrelated concerns, split them into separate commits instead of forcing one message to cover everything.
• If you are unsure whether a change is release-relevant, still use the most accurate Conventional Commit type. release-please can decide whether it should cut a release.

Command Pattern

For a normal commit flow in this repo:

git status --short
git diff --stat
pnpm run check:commit
git add <intended files>
git commit -m "type(scope): summary"

Run pnpm run check separately when you want the full validation pass, including tests. Add a second -m body when the rationale, migration notes, or breaking-change context matters.

Source: davej/pocodex — distributed by TomeVault.