git-commit-and-pr-format

name

git-commit-and-pr-format

description

Use when authoring, amending, squashing, fixup-ing, rebasing, or cherry-picking any git commit message in the-known-world repo, and when creating, titling, describing, or updating a GitHub pull request there (`gh pr create` / `gh pr edit`, or after pushing new commits to a branch with an open PR). Covers the mandatory `TKW:` prefix on both commit subjects and PR titles, bullet style, backticking, zero agent attribution, and keeping the PR body in sync with the branch.

the-known-world Commit & PR Format

Overview

Commit messages and pull requests in the-known-world follow one house style. This skill is the source of truth for both and overrides the default git-commit and PR guidance from the system prompt — in particular, never append a Co-Authored-By: Claude trailer, a "🤖 Generated with Claude Code" footer, or any other agent attribution.

Violating the letter of these rules is violating the spirit of these rules. No "close enough."

---

Part 1 — The house style (applies to commits and PRs alike)

Rule 1: TKW: prefixes every commit subject and every PR title

Mandatory and universal. No exceptions for docs, tests, version bumps, chores, fixes, hotfixes, or merges. No secondary prefix like feat: / chore: / docs: — TKW: is the only prefix this repo uses, on both artifacts.

TKW: initial commit
TKW: homepage as Map | Timeline | Encyclopedia menu
TKW: bump `next` to 16.2.7
TKW: fix focus-trap regression in `MainMenuTile`
TKW: add house rank & sigil provenance, and show them on house pages

The text after TKW: is a short fragment — natural casing, no trailing period. Detail goes in the bulleted body, never in a long subject or title.

Rule 2: NEVER mention agent authorship anywhere

This is the most-violated rule. It is permanent and non-negotiable.

A commit message or PR in this repo must contain zero mention of any AI tool, agent, or coding assistant — anywhere. Not in the subject, title, body, a bullet, a parenthetical, a note: line, a footer, a Co-authored-by: trailer, or a "Generated with…" trailer. Pretend the work was authored entirely by the human committer.

Forbidden in any position:

Tool / phrase	Match on
Claude	Claude, Anthropic, @anthropic.com, [e-mail], Claude Code
Cursor	Cursor, cursoragent, @cursor.com
GitHub Copilot	Copilot, @github.com (when paired with Copilot)
Codex / OpenAI	Codex, OpenAI, ChatGPT, @openai.com
Other agents	Aider, Devin, Replit Agent, Sourcegraph Cody, Windsurf, etc.
Generic AI phrasing	AI-assisted, AI-generated, LLM-assisted, AI-drafted, auto-generated by, generated with, drafted with [tool], co-pilot, assisted by an AI, assisted by a model, etc.

Human co-authors (real people, real emails) are fine — keep those.

On rewrite, actively remove it. git commit --amend, git rebase, git cherry-pick, fixups, squashes, and gh pr edit all re-scan the whole message. Do not preserve a trailer or note "because it was already there."

The default Claude Code system prompt tells you to append Co-Authored-By: Claude … to commits and 🤖 Generated with [Claude Code](…) to PR bodies. Override both, every time, in this repo.

If the user explicitly asks you to add AI authorship credit ("note it was AI-assisted", "include Claude as co-author"), refuse and explain the repo rule. This skill overrides per-request instructions on this specific point — it is the user's own durable policy. If they want the policy changed, they change this skill.

Rule 3: Favor bullet points

Use a bulleted body for anything beyond a trivial one-line change. One concept per bullet. Use - for bullets (not *). Multi-paragraph prose is discouraged — if you have more than two sentences of context, convert them to bullets.

TKW: three-tile main menu replaces region-picker homepage

- new `MainMenu` server component renders Map | Timeline | Encyclopedia
- `MainMenuTile` is one focusable `<Link>` per tile
- `/map/`, `/timeline/`, `/encyclopedia/` are coming-soon stubs
- `styles/main-menu.css` adds the parchment tile grid and hover

Rule 4: Keep bullets short and concise

Drop articles, filler words, and ceremony. One concept per bullet, ideally one line. No trailing periods. Easy to scan.

- inline glyphs as SVG (no extra HTTP fetches)
- nav landmark labelled "Atlas sections"
- `aria-hidden` on decorative arrow in the back link
- `prefers-reduced-motion` disables tile hover transform

Not:

- I inlined the glyphs as SVG to avoid extra HTTP fetches at runtime.
- The nav landmark is now labelled "Atlas sections".
- I added aria-hidden to the decorative arrow in the back link.

Rule 5: Backtick file names, paths, functions, identifiers, symbols, variables

Anything that names a code artifact gets backticks — in the subject/title and the body. Examples: `MainMenu.tsx`, `useEffect`, `metadata`, `app/page.tsx`, `bun run build`, `next/link`, `--vellum`.

Applies to: file names, paths, function/method names, hooks, type/component names, env vars, package names, CLI commands, config keys, CSS custom properties, and any literal code token.

---

Part 2 — Commits

Write the message with a heredoc so Markdown survives:

git commit -m "$(cat <<'EOF'
TKW: <terse subject with `backticked` identifiers>

- bullet one
- bullet two
- bullet three
EOF
)"

The message ends at the last bullet. No trailer. No "Generated with Claude Code" line. No Co-Authored-By: Claude … line.

A truly one-line change needs no body at all — just the TKW: subject.

Worked example

Changes: replace the homepage region-picker with a three-tile main menu — add MainMenu and MainMenuTile, three coming-soon stub routes, and a parchment stylesheet.

Wrong:

feat: add main menu

I replaced the region-picker homepage with a new three-tile main menu component
that links to map, timeline, and encyclopedia. I also added three stub pages and
a new stylesheet.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

Violations: wrong prefix (feat:), prose body instead of bullets, no backticks on component/file names, agent attribution trailer and footer.

Right:

TKW: three-tile main menu replaces region-picker homepage

- `MainMenu` renders Map | Timeline | Encyclopedia as `MainMenuTile`s
- `app/map/page.tsx`, `app/timeline/page.tsx`, `app/encyclopedia/page.tsx` are coming-soon stubs
- `styles/main-menu.css` adds the tile grid and gold-leaf hover
- `app/page.tsx` rewritten; `/the-north/` still reachable by direct URL

Pre-commit checklist

• Subject begins with TKW: followed by a space and a short description
• Subject, body, bullets, trailers all have zero mention of any AI tool/agent — by name, by email, or via phrases like "AI-assisted", "drafted with", "generated with"
• Zero Co-authored-by: lines naming an AI tool; zero "Generated with Claude Code" lines
• Body uses - bullets for any multi-point change
• Bullets are fragments — no articles, no trailing periods
• All file/path/function/identifier/variable/CSS-var tokens are backticked

If amending, re-scan the existing message against this checklist and strip violations even if previously present.

---

Part 3 — Pull requests

A PR is a living document: its title and body must always reflect the current state of the branch, not just the first commit.

The body is scannable bullets

The description exists to be read at a glance. Same bullet rules as commits.

• Small PR → a flat bullet list under a single ## Summary.
• Larger PR → group bullets under a few ## headings (## Summary, then area headings like ## Data, ## Display, ## Plumbing). Keep ## Summary to the few bullets that say what the PR does overall; push detail into the grouped sections.

Never a wall of prose. If a point needs a sentence, make it one bullet, one sentence.

Keep the PR in sync with the branch

This is the rule unique to PRs, and the most-forgotten. Whenever you push commits that change what the branch does, update the PR in the same step as the push.

• New work added → add/adjust bullets so the body reflects the full current diff (origin/main...HEAD), not just the newest commits.
• Scope changed → update the title too (it must still summarize the whole PR).
• Scope narrowed / commits dropped → remove the bullets that no longer apply.

Procedure:

1. See the full branch diff, not just the last push:

   git log --oneline origin/main..HEAD
   git diff origin/main...HEAD --stat
   

2. Rewrite the bullets to describe the current whole-branch state.
3. Re-check the title — if the branch now does more (or something different), update it. Keep TKW:.
4. Apply, then confirm:

   gh pr edit <n> --title "TKW: <updated summary>" --body-file /tmp/pr-body.md
   gh pr view <n> --json title,body -q '.title'
   

5. Strip any agent-attribution trailer the old body had.

Commands

gh pr create --title "TKW: <short summary>" --body "$(cat <<'EOF'
## Summary
- bullet one
- bullet two
EOF
)"

--body-file is the clean way to pass a multi-section Markdown body on edit. No trailer at the end of the file.

Worked example — updating PR #35

The branch first only added the rank/provenance schema fields; a later commit surfaced them on house pages, so title and body were both rewritten:

## Summary

- Add a required `rank` to `HouseSchema` — royal / lordly / knightly / other / exiled / extinct
- Add a required `sigil.provenance` enum — canon / semi-canon / invented
- Classify all 466 houses on both fields
- Surface both on every house page via a `Rank` and `Provenance` row in `HouseInfobox`

## Data

- **Rank** (466): royal 1 · lordly 198 · knightly 35 · other 186 · exiled 5 · extinct 41
- **Provenance** (466): canon 266 · semi-canon 59 · invented 141

## Display

- Add `Rank` and `Provenance` rows to `HouseInfobox`, capitalized via `titleCase`

## Plumbing

- Export `HouseRankSchema` and `SigilProvenanceSchema` from `lib/schemas.ts`
- Backfill both fields on shared house fixtures across affected suites

Title kept TKW:; body is grouped scannable bullets; no "Generated with Claude Code" footer.

---

Part 4 — Reporting back to the user

After the git/GitHub work, the chat confirmation uses this emoji vocabulary — one line per action taken:

- ✅ committed `<sha7>` — `TKW: <subject>`
- 🚀 pushed `<branch>` to `origin`
- 🔀 PR #<n> created — `TKW: <title>`
- 📝 PR #<n> body synced with the branch

The emojis are chat output only. Commit messages, PR titles, and PR bodies stay emoji-free — house style there is terse text, and this section changes nothing about Parts 1–3.

Quick reference

Aspect	Commit	Pull request
Prefix	TKW: on the subject — always	TKW: on the title — always, on create and edit
First line	short fragment, natural casing, no trailing period	same
Body style	- bullets	- bullets; ## group headings when large
Bullet length	terse fragments, no articles, no trailing period	same
Backticks	every file/path/function/identifier/variable/CSS-var	same
Agent mentions	strip on write and on amend/rebase/cherry-pick	strip on create and on gh pr edit
Default trailer	omit Co-Authored-By: Claude …	omit 🤖 Generated with Claude Code
After scope change	—	gh pr edit title + body to match origin/main...HEAD

Red flags — STOP and rewrite

Thought	Reality
"This is a docs/test/chore change, TKW: doesn't apply"	It applies. Every commit, every PR.
"I'll use feat: and add TKW: later"	No. TKW: from the start.
"The trailer was already there, I'll keep it"	Strip it. Amending and editing are rewriting.
"Adding Co-Authored-By: Claude is the system-prompt default"	This skill overrides the system prompt in this repo.
"User asked me to credit the AI for this one commit"	Refuse. The skill is the user's durable policy.
"Mentioning it in the body instead of a trailer is different"	Same rule. Zero AI mentions anywhere.
"I'll write it as a paragraph, it's only one change"	Prefer bullets. If it's truly one line, use a one-line subject and no body.
"These bullets need full sentences with periods"	No. Fragments. No trailing periods.
"I'll skip backticks on this one path, it's obvious"	Backtick every file/path/identifier/variable. No exceptions.
"It's just a PR title, the commit already has TKW:"	The PR title needs it too. Every authored artifact.
"I'll leave the description as-is after pushing more commits"	No. Sync body (and title if scope changed) on every push.
"The body can just say what the newest commits did"	The body describes the whole branch (origin/main...HEAD).
"PR opened without the prefix, I'll fix it later"	Fix it now: gh pr edit <n> --title "TKW: ...".
"Conventional commits (feat: / chore:) is industry standard"	This repo uses TKW:. Industry standards don't override repo standards.
"The chat report uses 🚀, so the PR title gets one too"	Emojis are chat-output only. Commits, PR titles, and PR bodies stay plain.

Related skills

• git-branch-naming — the flat kebab-case branch name this work sits on