[PATCH 01/12] CLAUDE.md: consolidate and strengthen commit guidelines

From: Daniel Gomez <[email protected]>

The commit guidelines were scattered across five separate sections
spread over 70 lines, making it easy to accidentally skip critical
rules like the shopping cart list prohibition. Rule 4 about avoiding
bullet points was particularly easy to overlook because it lacked the
bold warnings and visual emphasis that made Rule 3 impossible to miss.
This was causing repeated violations that required constant manual
correction.

All five commit rules are now consolidated into a single "Git Commit
Guidelines" section with numbered rules (Rule 1/5 through Rule 5/5).
This makes it impossible to miss any rule since they are all together
in one place with clear numbering. The original rule order is preserved.

Rule 4 now has a bold header matching Rule 3's style that reads
"CRITICAL RULE: NEVER USE BULLET POINTS OR ITEMIZED LISTS IN COMMIT
MESSAGES" to make the prohibition unmissable. The WRONG examples section
was expanded to include multiple patterns of bullet point violations,
showing both the problematic formats and their correct plain English
alternatives. This provides concrete guidance on how to convert lists
into narrative paragraphs.

A new commit message template section was added immediately after Rule 5
to serve as a reference for AI assistants when drafting commits. The
template explicitly shows the correct format with inline reminders about
avoiding bullet points. The template's key requirements are presented in
plain English paragraphs rather than bullet points to maintain consistency
with the prohibition on lists.

These changes ensure that Rule 4 has the same visual weight and clarity
as Rule 3, preventing future violations through consolidation, bold
emphasis, expanded examples, and explicit formatting guidance.

Generated-by: Claude AI
Signed-off-by: Daniel Gomez <[email protected]>
---
 CLAUDE.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 69 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index aabf543c..28920130 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -407,21 +407,25 @@ This framework is designed by kernel developers for kernel developers,
 providing production-ready automation for kernel testing and development
 workflows.
 
-## One commit per change
+## Git Commit Guidelines
+
+All commits must follow these 5 rules:
+
+### Rule 1/5: One Commit Per Change
 
 As with the Linux kernel, this project prefers commits to be atomic and to
 the point. We don't want spell fixes to be blended in with code changes.
 Spell fixes should go into separate commits. When in doubt, just don't do
 any spell fixes unless asked explicitly to do that.
 
-## Use the Signed-off-by tag
+### Rule 2/5: Use the Signed-off-by Tag
 
 We want to use the Signed-off-by tag which embodies the application of the
 Developer Certificate or Origin. Use the git configured user name and email
 for the Signed-off-by tag (check with `git config user.name` and
 `git config user.email`).
 
-## Use Generated-by: Claude AI
+### Rule 3/5: Use Generated-by: Claude AI
 
 Use this tag for code generated by Claude code AI. Put this before the
 Signed-off-by tag.
@@ -455,17 +459,48 @@ Generated-by: Claude AI
 Signed-off-by: Your Name <[email protected]>
 ```
 
-## Avoid Shopping cart lists
+### Rule 4/5: Avoid Shopping Cart Lists
+
+**CRITICAL RULE: NEVER USE BULLET POINTS OR ITEMIZED LISTS IN COMMIT MESSAGES**
 
 Generative AI seems to like to make commit logs long itemized lists of things
 it did. This is stupid. This should be avoided. It is creating very silly
-commit logs. Use plain english and get to the point. Be as clear a possible
+commit logs. Use plain English and get to the point. Be as clear as possible
 and get to the point of not what you want to communicate, but rather what
 will make a reviewer easily understand what the heck you are implementing.
 
 You should *think* hard about your commit log, always.
 
-## Code Quality Requirements
+**WRONG - Shopping cart list with bullet points:**
+```
+Refactored to separate concerns:
+- Distribution files handle package installation and set nfs_server_service
+  variable (nfs-kernel-server for Debian/Ubuntu, nfs-server for RedHat/Fedora)
+- Single systemd task in main.yml handles service enablement using the variable
+```
+
+**WRONG - Change list:**
+```
+Fix by changing:
+  - mirror_service_status.item → mirror_service_status.results
+  - mirror_timer_status.item → mirror_timer_status.results
+```
+
+**Correct - Plain English:**
+```
+Each distribution file now handles package installation and sets the
+nfs_server_service variable to the appropriate service name for that
+distribution. A single systemd task in main.yml then handles service
+enablement using the variable.
+```
+
+**Correct - Plain English:**
+```
+Change both debug tasks to iterate over the .results list instead of
+the non-existent .item attribute.
+```
+
+### Rule 5/5: Run make style Before Committing
 
 **IMPORTANT**: Before completing any work, you MUST run `make style` to check for
 both whitespace issues and commit message formatting. This ensures code consistency
@@ -481,6 +516,34 @@ The style checker will identify:
 Fix all reported issues before submitting your work. The `make style` command
 checks both file whitespace and the most recent commit message format.
 
+### Commit Message Template for AI Assistants
+
+**IMPORTANT: All AI-generated commits MUST follow this exact format:**
+
+```
+subsystem: brief description in imperative mood (max 50 chars)
+
+Detailed explanation of the problem being solved and why the change
+is needed. Use plain English paragraphs - NEVER use bullet points or
+itemized lists.
+
+Explain what the change does and how it solves the problem. Focus on
+clarity for reviewers who need to understand the implementation.
+
+Multiple paragraphs are fine when needed to explain complex changes.
+
+Generated-by: Claude AI
+Signed-off-by: Name <[email protected]>
+```
+
+**Key requirements:** The subject line must use subsystem prefix in imperative
+mood with a maximum of 50 characters. The body must use plain English paragraphs
+only with NO bullet points or lists. Generated-by must be immediately followed
+by Signed-off-by with no blank lines between them. Use the values from
+`git config user.name` and `git config user.email` for the Signed-off-by tag.
+
+## Code Quality Requirements
+
 ### Rust Code Quality
 
 For Rust code in kdevops (workflows/rcloud, etc.), ALWAYS run both:

-- 
2.51.0