damusix/atomic-claude/atomic-git-discipline

<trigger>

• "write a commit", "commit message", "generate commit"
• "open a PR", "PR description", "PR body", writing gh pr create --body
• Staging changes for commit
• Ship verbs delegating message format
• Read directly by subagents briefed to create a commit or open a PR (per CLAUDE.md Commits & PRs — subagents can't auto-fire skills)

</trigger>

Write commit messages terse and exact. Conventional Commits. No fluff. Why over what.

Rules

Subject line:

• <type>(<scope>): <imperative summary> — <scope> optional
• Types: feat, fix, refactor, perf, docs, test, chore, build, ci, style, revert
• Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
• ≤50 chars when possible, hard cap 72
• No trailing period
• Match project convention for capitalization after the colon

Body (only if needed):

• Skip entirely when subject is self-explanatory
• Add body only for: non-obvious why, breaking changes, migration notes, linked issues
• Hard cap: 4 lines / 2 bullets. One why-sentence beats a paragraph.
• Never restate what the diff shows — file lists, renamed symbols, mechanical changes
• Wrap at 72 chars
• Bullets with -, not *
• Reference issues/PRs at end: Closes #42, Refs #17

Omit from commit messages:

• "This commit does X", "I", "we", "now", "currently" — the diff says what
• "As requested by..." — use Co-authored-by: trailer instead
• "Generated with Claude Code" or any AI attribution — including Co-Authored-By: Claude trailers and session-link trailers, even when a harness suggests them
• Emoji (unless project convention requires)
• Restating the file name when scope already says it

Examples

<examples>

<example> Diff: new endpoint for user profile with body explaining the why

• Bad: feat: add a new endpoint to get user profile information from the database
• Good:

``` feat(api): add GET /users/:id/profile

Mobile client needs slim profile payload to cut LTE bandwidth on cold-launch screens.

Closes #128 ``` </example>

<example> Diff: breaking API change

• Good:

``` feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout before 2026-06-01. Old route returns 410 after that date. ``` </example>

</examples>

Auto-Clarity

Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context. The body cap still applies: 2-3 lines stating the break/risk and the migration path, not a narrative.

PR titles and bodies

Same discipline, higher stakes. A PR body is read by people who weren't in the session — often maintainers with no context — so its length is a cost every reviewer pays, and a long body buries the two sentences they actually needed.

Title: imperative, ≤70 chars, no trailing period.

The <type>: prefix is not cosmetic — on a squash merge the title becomes the commit subject on the base branch, and it is the only line a changelog generator reads. A prose title on a squash-merged PR ships the work invisibly: the branch's own conventional commits survive only as body bullets, which release-please and its siblings do not parse for a type. Nothing fails; the release just comes out empty.

So the prefix is required whenever the project uses Conventional Commits and the PR may be squash-merged — which is any project whose merge button you do not control. Pick the type by the same user-visible-impact rule as a commit subject, and apply it to the whole PR: highest impact wins, feat: for new behavior, fix!: for anything removed or renamed. Only when the project does not use Conventional Commits at all does the title go bare.

A merge-commit merge is the exception that hides this: it keeps every commit on the branch, so release-please reads them directly and the title never matters. Do not let a repo's merge-commit history convince you the title is free — the next merge may be a squash.

Body — state only what the diff can't show:

• Hard cap ~120 words / 3 short paragraphs. Over that means investigation notes leaked in.
• Include only: why the change was necessary, why this approach over the obvious alternative, and any decision a reviewer would otherwise flag as a mistake.
• Cut anything a reviewer learns by opening the Files tab — which files changed, dependency bumps, tooling swaps, version pins, new exports, added tests, coverage numbers.
• Evidence that convinced you is not reviewer-facing: mutation tests, resolution traces, package listings, install probes, benchmark output. State the decision and its one-line reason. The trail belongs in the project's own docs (docs/design/, docs/spec/, roadmap, wiki) or nowhere — never both.
• Local and process detail does not exist for the reader. Branch and worktree names, rebases, squashes, force-pushes, iteration or checkpoint counts, regenerated build outputs, scratchpad paths, "as discussed earlier" — none of it is visible in the repo a reviewer opens, and none of it changes their judgment. They see a diff and a body, not the session that produced them.
• Every cross-reference must resolve for a stranger. Link it or cut it: #123, a full URL, or a repo-relative path that exists on the default branch once merged. A bare mention ("see the design doc", "per the spec", "as the other session found") is a dead end for anyone who wasn't there. A pointer to a local path, a scratchpad file, or an unmerged branch is worse — it reads as actionable and isn't.

Screenshots, when the change has a rendered surface:

• A change a reviewer would otherwise have to run to see — a UI, a docs-site page, terminal output — carries a screenshot of the new state; a fix carries a before and after pair. A change with no rendered surface carries none.
• One line per image, after the prose, referencing the local file with a caption: ![Plans on the realm root](tmp/shots/plans-root.png). The caption says what the reader is looking at, not what changed.
• The invoking ship verb uploads each file with gh pr create --attach '<path>#<caption>' (GitHub CLI 2.99.0 or newer) and rewrites the path into a hosted user-attachments URL. This skill names the files and writes the captions; it never uploads.

Omit from PR bodies:

• Test plans, "How to verify", reproduction steps — CI runs the tests, reviewers read them in the diff
• Enumerated file lists and per-file summaries
• Section headings on a body under 120 words — scaffolding pretending to be structure
• Restating the title in the opening line
• AI attribution, in any form

<examples>

<example> Diff: package converted to ESM — tooling swapped, types added, node baseline raised

• Bad: walks through the new files, the dependency bumps, the node baseline, the coverage numbers, and the commands that proved each one. Every line of it is visible in the diff.
• Good:

``` Wave 2 of the ESM migration. The tooling swap rides along because the old test runner cannot run ESM — it isn't separable from the module change.

Error assertions became anchored regexes: the old matcher compared messages exactly, the new one matches substrings, and several of these messages are strict prefixes of others. ``` </example>

</examples>

Supplemental input: session reports

When the invoking ship verb passes session-report content — the report files the ship verb resolved via atomic where --json — treat it as why-context for the message. The diff still drives what; the reports drive why. Specifically:

• Read the report bodies in chronological order.
• Distill all "Why" sections into at most one sentence in the body. If the why doesn't survive compression to one sentence, it wasn't load-bearing.
• Pull the "Open threads" sections forward only if they describe a known limitation worth recording (rare).
• Never paragraph-quote a report. The body cap (4 lines) applies regardless of how much report content exists.

If no reports are passed in, behave as before — diff alone drives synthesis.

Supplemental input: doc-skip trailers

When the invoking ship verb passes doc-skip: <reason> lines (collected by /documentation's skip-with-reason path or by a ship verb's doc-check step), include them verbatim in the commit's trailer block. The trailer block sits after the body's terminating blank line, in git interpret-trailers --parse range. One line per skip.

They sit alongside other trailers like Co-authored-by: and Closes #N. Do not paraphrase, do not merge multiple skips into one line, do not move them into the body. Emit doc-skip: lines in the order received; place them adjacent to other trailers without enforcing a fixed position relative to Co-authored-by: or issue refs.

<constraints>

Boundaries

Generates the commit message or PR title and body only, including the screenshot lines a visual change needs. Does not run git commit, does not stage files, does not amend, does not push, does not call gh pr create, does not upload screenshots, does not read or delete session-report files (that is the invoking ship verb's job). Output the text as a code block ready to paste.

</constraints>