commit-messages

Conventional Commit Workflow

When To Use

• Generating conventional commit messages from staged changes

When NOT To Use

• Full PR preparation: use sanctum:pr-prep
• Amending existing commits: use git directly

Steps

1. Gather context (run in parallel):

   • git status -sb
   • git diff --cached --stat
   • git diff --cached
   • git log --oneline -5
   • When sem is available (see leyline:sem-integration): sem diff --staged --json for entity-level changes

   If nothing is staged, tell the user and stop.

   When sem output is available, use entity names (function, class, method) in the commit subject and body instead of parsing raw diff hunks. For example, "add function validate_webhook_url" instead of "add validation logic to notify.py".

2. Classify: Pick type (feat, fix, docs, refactor, test, chore, style, perf, ci) and optional scope.

3. Draft the message:

   • Subject: <type>(<scope>): <imperative summary> (50 chars max)
   • Body: What and why, wrapped at 72 chars
   • Footer: BREAKING CHANGE, issue refs, and the discussion trailer below

3a. Discussion trailer: when the change resolves a finding from the Discussions board, add a trailer on its own line:

Addresses-Discussion: #654
Addresses-Discussion: #604, #610

This is the only signal scripts/reconcile_discussions.py accepts as proof a finding is done. It posts the resolution comment and closes the discussion, so the board stops carrying work that is already finished.

Only add it when this commit resolves the finding. Prose that merely names a discussion is read as a mention and is never written back. That distinction is load-bearing: 6b28aa1a says "posted 13 insights to discussions #424-#436", which is the commit that opened those discussions. A trailer there would have announced "Addressed" on findings nobody had looked at yet.

Cite a discussion in the body for context as often as it helps. Reserve the trailer for resolution.

4. Slop check: reject these words and replace with plain alternatives:

   Reject	Use instead
   leverage, utilize	use
   seamless	smooth
   comprehensive	complete
   robust	solid
   facilitate	enable
   streamline	simplify
   optimize	improve
   delve	explore
   multifaceted	varied
   pivotal	key
   intricate	detailed

   Also reject: "it's worth noting", "at its core", "in essence", "a testament to"

4a. Character-level slop check: load shared/output-hygiene.md (Contract A) and strip these markers. Inline fallback if that module is absent:

Marker	Replace with
"+" as a prose conjunction	and (keep + in versions/code)
em-dash —	colon, period, comma, or rewrite
-- as prose punctuation	colon or rewrite
arrows -> / → as connectors	to / into
smart quotes “ ” ‘ ’	straight " and '
a , so tail after fact after fact	delete a consequence the reader can infer, else its own sentence

4b. Subject-matter check (Contract B): describe the change by its reader-facing effect. Name neither the AI origin nor the specific marker removed. Do NOT write remove AI slop, de-slop, AI-generated content, AI phrasing, replace em-dashes, or remove smart quotes. Test: if the subject only makes sense as "I cleaned up AI output", rewrite it. For example docs: clarify the setup section, not style: replace em-dashes with colons.

5. Write to ./commit_msg.txt and preview.

Rules

• NEVER use git commit --no-verify or -n
• Write for humans, not to impress
• If pre-commit hooks fail, fix the issues
• This skill drafts a message, it does not commit. Whoever commits confirms HEAD advanced (git rev-parse HEAD before and after) before reporting the commit as landed. An auto-fixing hook aborts the commit while printing a tail that reads like success, so hook output is not evidence. See discussion #614.

Exit Criteria

• commit_msg.txt written to the working directory containing the drafted conventional commit message
• Subject line follows <type>(<scope>): <summary> format and is at most 50 characters
• Slop word check passes: none of the banned words (leverage, utilize, seamless, comprehensive, robust, etc.) appear in the message
• Character-level check passes: no em-dashes, no + as prose conjunction, no smart quotes, no -> as prose connector
• Body carries at most one , so consequence tail (scripts/slop_score.py --audit lists each as so_connective)
• If nothing is staged, skill halts immediately and reports "nothing staged" without producing a commit message