From 060636d2f9acc8c37bc5873f109ffa16c270f98a Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 24 Apr 2026 19:06:34 -0500 Subject: docs(commits): add content scope rule for public artifacts PR descriptions, Linear ticket bodies, and PR review comments are visible to the team. New section codifies what not to mention (local paths, private repos, personal tooling) and a concise four-section structure for shipped-fix descriptions: Problem, Fix, Why this fixes it, How it was tested. --- claude-rules/commits.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/claude-rules/commits.md b/claude-rules/commits.md index 615ea32..7fcd4ba 100644 --- a/claude-rules/commits.md +++ b/claude-rules/commits.md @@ -84,6 +84,33 @@ argument is `Mission`, not `unknown`" beats the full inference chain that produces that signature. Keep the terms a reader will grep for, drop the ones that name compiler internals. +## Content scope for public artifacts + +PR descriptions, Linear ticket bodies, and PR review comments are +visible to the team and to anyone with read access to the repo or +project. Don't mention: + +- Local file paths on the user's personal machine. +- Private repos by name (e.g. a personal notes repo, a career repo). +- Personal tooling or workflow the team doesn't share. +- Anything a teammate couldn't reproduce or act on from public sources. + +Rule of thumb: if a teammate couldn't find the referenced thing without +the user's help, don't reference it. + +Structure shipped-fix descriptions in this order, using the headings +verbatim: + +1. **Problem** — what's wrong, with enough detail that a teammate can + recognize the same failure mode in their own work. +2. **Fix** — what changed. +3. **Why this fixes it** — causal link, one or two sentences. +4. **How it was tested** — skip for proposals, specs, or discussions. + Required for shipped fixes. + +Verbose preambles, motivational language, and context unrelated to the +problem belong out. Same conciseness pressure as commit-message bodies. + ## Review and Publish Commits and PRs are team-visible, permanent, and hard to amend once shared -- cgit v1.2.3