Commit

Commit Skill

Analyze code changes, group them into logical packages where appropriate, to create sequential, clear, descriptive commits with effective titles and detailed descriptions.

---

Levels of Detail

Level	Component	Purpose
Highest	Title	Single sentence capturing all changes comprehensively yet succinctly
Middle	Description	One level deeper - enough to fully understand without viewing files
Lowest	Files	The actual diff - reader can inspect directly if needed

---

Step 1: Grouping

Analyze all changes and determine commit packages.

Grouping Priority:

Priority	Criterion	Example
1	Feature cohesion	All files for user auth feature
2	Directory scope	All changes in auth/ module
3	Logical separation	Config changes separate from code
4	Dependency order	Interface before implementation

Split Decision:

• Can describe in one sentence? → Single commit
• Multiple unrelated changes? → Split by concern
• Too complex for one sentence? → Split by logical phase

Commit Sequence (when splitting):

• What change enables or defines the others? → Commit first
• Would a reviewer understand each commit in isolation?
• Does the sequence tell a coherent story?
• Order so earlier commits provide context for later ones

---

Step 2: Title

Write one sentence that:

• Captures ALL changes at the highest level
• Is concise but comprehensive - effective word choice matters
• Clearly conveys what changed without granular file-by-file details
• Capitalize first letter and proper nouns (Claude Code, GitLab, OAuth2, README)
• Imperative mood ("Add" not "Added")
• No period at end
• Max 72 characters (prefer under 50)

Good:

• Add OAuth2 authentication to login flow
• Update GitLab MR skill to fetch all comments
• Refactor design guide into modular directory structure

Bad:

• fix bug (too vague)
• Updated the thing (past tense, vague)
• Add feature, fix bug, update docs (multiple things - split it)
• Add auth system — OAuth2 + JWT + session management (details after dash belong in description, not title)

---

Step 3: Description

Write bullet points (or other clear format) that:

• Go one level deeper than the title
• Provide enough detail that reader fully understands WITHOUT looking at files
• Stay concise - not overly verbose or exhaustive
• Scale detail to change size. A mechanical 3-file rename needs 2 bullets. Save the full narrative for complex changes.
• Complement the title, don't repeat it

Example:

Add 8-step autonomous session protocol with cross-references

- Create autonomous-protocol.md defining discover/plan/execute/verify/document/commit/continue/stop steps
- Add cross-references to memory.md, execution.md, and core.md
- Create continuation-prompt-template.md for consistent session prompts
- Update CHANGELOG with Phase 3 entries

---

Step 3.5: Verify

Before staging and committing, confirm:

• Type checker passes on changed files
• Linter passes on changed files (check the project's linter config if unsure what rules apply)
• Tests pass

Fix issues first. A commit that triggers a hook failure or needs a follow-up "fix lint" commit is not a clean commit.

---

Step 4: Execute

Stage files and commit using HEREDOC format:

git add file1.ts file2.ts

git commit -m "$(cat <<'EOF'
Title sentence here

- Description bullet 1
- Description bullet 2
- Description bullet 3
EOF
)"

git log -1 --oneline

If multiple commits, repeat for each in the planned sequence.

---

Rules

• Never add Co-Authored-By or other attribution lines - only the user is credited
• Never use --no-verify - hooks exist to catch errors before CI does
• Never ask questions - analyze and commit
• Match project style - check recent commits for conventions