// Canonical rules for writing git commits in the Shift codebase. Use whenever the user asks to commit, stage and commit, or "make a commit" — and whenever you're about to draft a commit message. Enforces conventional prefixes, concise subjects, and splitting unrelated changes into separate commits.
Add or revise source-level JSDoc for Shift APIs. Use this skill before writing or editing documentation comments for exported classes, methods, constructors, domain data structures, render frames, reactive state, or any API where caller intent, side effects, lifetime, ownership, or nullability are easy to misunderstand.
Update or create DOCS.md files for Shift subsystems. Use this skill whenever the user asks to update docs, refresh documentation, create a DOCS.md, write module documentation, or says "update docs for X". Also trigger after completing a large feature when Claude.md says to update docs — check if any DOCS.md in the affected subsystem needs refreshing.
Canonical rules for writing tests in the Shift codebase. Use whenever you add, rewrite, or review a `.test.ts` file — or any time you're about to mock, stub, or spy your way around a testing problem. This repo has deliberately swept mock-based testing out, and this skill is what keeps it out.
Find and remove dead code (unused files, exports, class members) using Knip as a candidate generator, then verify each candidate through AST-level analysis and interface tracing before removing anything. Use when the user asks to clean up unused code, find dead code, or reduce the codebase.
| name | commit |
| description | Canonical rules for writing git commits in the Shift codebase. Use whenever the user asks to commit, stage and commit, or "make a commit" — and whenever you're about to draft a commit message. Enforces conventional prefixes, concise subjects, and splitting unrelated changes into separate commits. |
The goal: a git log --oneline that reads like a changelog. Each line tells you what changed and why in under ~70 characters, with a prefix that lets you grep for features vs fixes vs refactors.
Every commit subject is <type>: <concise description>. Every commit is one logical change.
If you can't describe the change in one short clause, it's probably two commits.
Before writing any commit message, ask the user to describe the changes in their own words. They know the why; you only see the diff. A one-line description from the user beats five minutes of you guessing from code.
Skip this step only if:
When asking, keep it tight:
"Before I commit — give me a one-line description of what these changes do and why. If multiple things are in flight, list them separately so I can split commits."
| Type | Use for |
|---|---|
feat | New user-visible functionality |
fix | Bug fix |
refactor | Code change with no behavior change |
test | Adding or rewriting tests, no production code changes |
docs | Documentation only (DOCS.md, README, comments) |
perf | Performance improvement, no behavior change |
style | Formatting only (prettier, oxlint --fix). Not "look-and-feel UI tweaks** — those are feat or fix. |
build | Build system, native compile, package scripts |
chore | Tooling, config, dependencies, repo housekeeping |
ci | CI workflows |
If a change touches multiple types, split it. A feat that also fixes an unrelated bug is two commits.
<type>: prefix. Aim for 50.feat: add ..., not feat: Add ....fix: GlyphView interpolation on composite scrub is fine; fix: update GlyphView.ts line 142 is not).Most commits don't need a body. Add one when:
When you write a body:
Before staging, look at what's modified and ask: does this collapse to one logical change, or several?
Strong signals to split:
chore: regenerate types separate from the feat).style: separate.Signals to keep together:
When in doubt: propose the split to the user and let them confirm before you stage anything. A wrong split is annoying to unwind.
After the user describes the changes, send a short plan like:
Proposed commits:
refactor: move text/* under lib/text— pure file moves, no logic changesfeat: <thing the user described>— Editor.ts, NativeBridge.ts, App.tsxtest: cover <thing>— new Editor.test.ts and updated suitesdocs: refresh text/ DOCS.mdWant me to stage and commit in that order?
Wait for confirmation before running git add / git commit.
Good (keep doing these):
feat: text-system rewrite — bottom-up rebuild around Cell + TextRunfix: canvas interpolates composite components on slider scrubtest: GlyphView interpolation against MutatorSansrefactor: sweep leaky naming suffixesBad (don't do these):
add variation cache to the editor, fix bug where edit sessions did not have current variation when opening a new glyph for editing
→ no prefix, two unrelated changes, runs to ~120 chars. Should have been:
feat: cache variation state on Editorfix: hydrate edit session with current variation on glyph openstyle fixes
→ vague. What style? Where? Use style: prettier sweep across renderer/ or just merge into the parent commit.component restructure
→ no prefix, says nothing. refactor: split <X> into <Y> + <Z>.more home sidebar design
→ "more" is a smell that says "I didn't bother to describe this". Squash into the parent or rename to feat: home sidebar — <specific addition>.git status and git diff (and git diff --cached if anything is already staged) in parallel. Read enough of the diff to know what changed — don't trust the file list alone.git log --oneline -10 to match style and prefix conventions.git add <paths> — never git add -A or git add .. Per-commit staging keeps splits clean.git commit -m "$(cat <<'EOF' ... EOF)" (heredoc, so multi-line bodies survive shell quoting).git status after each commit to confirm what's left.git commit until the user has explicitly asked for a commit, or has confirmed the proposed split.--no-verify, --no-gpg-sign) unless the user explicitly asks. If a pre-commit hook fails, fix the issue and create a NEW commit — do not --amend..env, credentials.json, anything with API keys in the diff). Flag them and ask.-A / . — pick paths.