Add commit and PR title conventions to prevent duplicate references (#126)

Author: lex57ukr

.claude/commands/pr-create.md

@@ -145,6 +145,9 @@ Create an outcome-focused title that:
 - Uses imperative mood ("Add...", "Enable...", "Fix...")
 - Matches the issue title style when applicable
 - Is concise (50-72 characters preferred)
+- **Does NOT include issue references** (e.g., avoid `Fix bug (#42)`)—GitHub automatically
+  appends the PR number during squash merge; issue linking belongs in the body via `Refs #NN`
+  or `Fixes #NN`
 
 ### 9. Preview and Confirm
 

.github/pull_request_template.md

@@ -1,9 +1,10 @@
 <!--
 PR workflow reminder:
 - Use a clear, outcome-focused title (this becomes a release note entry)
+- Do NOT include issue numbers in the title — GitHub appends the PR number on squash merge
 - Apply appropriate labels (e.g. enhancement, documentation, bug)
 - Use special labels (`breaking-change`, `security`, `dependencies`) intentionally — they affect release notes
-- Reference related issues using `Refs #NN` or `Fixes #NN`
+- Reference related issues in the description using `Refs #NN` or `Fixes #NN`
 - Squash merge is preferred unless stated otherwise
 -->
 

CLAUDE.md

@@ -245,6 +245,16 @@ Template repository URLs are configurable via settings.
 - Target framework defined centrally in `Directory.Build.props`; see
   `docs/how-to/how-to-upgrade-dotnet.md` for upgrade instructions
 
+## Git Workflow
+
+This project uses squash merges. Follow the conventions in
+[docs/how-to/how-to-workflow.md](docs/how-to/how-to-workflow.md), particularly:
+
+- **Commit messages**: Do not reference issue numbers; short descriptive summaries are fine
+- **PR titles**: Must be release-note quality; do not include issue references (GitHub appends
+  the PR number on squash merge)
+- **Issue linking**: Use `Fixes #NN` or `Refs #NN` in the PR **description**, not the title
+
 ## CI/CD and Release Process
 
 ### GitHub Workflows

docs/how-to/how-to-workflow.md

@@ -34,12 +34,30 @@ GitHub generates branch names in the format `<issue-number>-<issue-title-slug>`
 (e.g., `42-fix-login-bug`). Following this pattern ensures consistency whether the branch
 is created automatically or manually.
 
+#### Writing Commit Messages
+
+Since PRs are squash-merged, individual commits don't need to be release-note quality—but
+good commit messages still help reviewers and your future self understand the progression of changes.
+
+**Do:**
+- Write short, descriptive summaries (e.g., `Add validation for empty input`)
+- Use commits to mark logical checkpoints (e.g., `WIP: basic structure`, `Add tests`, `Fix edge case`)
+- Feel free to use `WIP`, `fixup`, or `checkpoint` prefixes for in-progress work
+
+**Don't:**
+- Reference issue numbers in commit messages—the PR description handles issue linking
+- Worry about perfect formatting—squash merge discards individual commit messages
+- Write multi-paragraph commit bodies unless the context is genuinely useful for review
+
 ### 3. Opening a Pull Request
 
 Open a Pull Request when the work is ready for review or merge.
 
 - The PR title **must be release-note quality** (it will appear verbatim in release notes)
-- The PR description should reference the issue using one of the following:
+- **Do not include issue references in the PR title** – GitHub automatically appends the PR number
+  during squash merge, so including `#<issue-number>` in the title results in duplicate references
+  (e.g., `Fix bug (#42) (#43)`)
+- Reference the issue in the **PR description** using one of the following:
     - `Fixes #<issue-number>` – closes the issue when merged
     - `Refs #<issue-number>` – links the issue without closing it