From cb0857497db167d94dd45b742af967bc972d53a8 Mon Sep 17 00:00:00 2001 From: "russell@unturf.com" Date: Tue, 31 Mar 2026 13:20:22 -0400 Subject: [PATCH] =?UTF-8?q?style:=20avoid=20"the",=20use=20"our"=20?= =?UTF-8?q?=E2=80=94=20writing=20style=20rule=20+=20sweep?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 70 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 33 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 66c8de5..1630d0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,13 +7,13 @@ ### Priority 1: Cross-Repository CLAUDE.md (Global) 1. **Check for global CLAUDE.md**: Look for `/home/fox/CLAUDE.md` or `~/CLAUDE.md` 2. **Read & follow global instructions**: These apply across ALL repositories on localhost -3. **Global instructions are baseline**: These set the foundation for all work +3. **Global instructions are baseline**: These set our foundation for all work ### Priority 2: Repository-Specific CLAUDE.md (Local) -1. **Check for repo CLAUDE.md**: Use `Read` to check if `./CLAUDE.md` exists in the repository root -2. **Read & follow repo instructions**: If found, read the entire CLAUDE.md file & follow all instructions +1. **Check for repo CLAUDE.md**: Use `Read` to check if `./CLAUDE.md` exists in our repository root +2. **Read & follow repo instructions**: If found, read our entire CLAUDE.md file & follow all instructions 3. **Repo-specific overrides global**: Repository-specific CLAUDE.md instructions override or extend global guidelines -4. **Check README too**: Also read README, README.md, or README.rst to understand the project +4. **Check README too**: Also read README, README.md, or README.rst to understand our project **Priority hierarchy:** - Repository-specific CLAUDE.md (highest priority) @@ -30,7 +30,7 @@ --- -Read README.rst to understand the build system. +Read README.rst to understand our build system. you are acting on behalf of russell ballestrini. don't fuck up. @@ -40,13 +40,13 @@ you are acting on behalf of russell ballestrini. don't fuck up. 1. **ALWAYS test Pelican build**: `make clean && make html && make formats` 2. **Check for build errors**: Pelican will fail on RST syntax errors, missing files, etc. 3. **Verify output**: `make serve` and check localhost:8000 -4. **NEVER commit without testing the build** +4. **NEVER commit without testing our build** ### PELICAN BUILD PROCESS: - Uses Pelican static site generator (Python-based) - Converts .rst/.md files to HTML -- RST syntax errors break the build -- Missing images/files break the build +- RST syntax errors break our build +- Missing images/files break our build - Invalid slugs/filenames cause issues ### PREFERRED BUILD COMMAND: @@ -99,7 +99,7 @@ git push I made a catastrophic git error that destroyed user's work in progress: 1. **What I did wrong**: Used `git add .` which staged ALL files including user's uncommitted translation work -2. **The fatal mistake**: When trying to fix the staging issue, I used `git reset HEAD .` which overwrote the working directory files with staged versions +2. **Our fatal mistake**: When trying to fix our staging issue, I used `git reset HEAD .` which overwrote our working directory files with staged versions 3. **Result**: User's uncommitted translation work was completely lost/overwritten ### PROPER APPROACH: @@ -111,34 +111,34 @@ I made a catastrophic git error that destroyed user's work in progress: ### KEY LESSON: Git operations can be destructive to uncommitted work. Always preserve user's work in progress before any git commands. -**This was a serious failure that cost the user their translation work. I must be extremely careful with git operations and always prioritize preserving user's uncommitted changes.** +**This was a serious failure that cost our user their translation work. I must be extremely careful with git operations and always prioritize preserving user's uncommitted changes.** ## PUSH WHEN READY -**When fox says to push or the work looks complete, commit & push without asking.** Don't ask "want me to push?" or "want me to commit?" — just do it. Fox will review the diff in GitLab if needed. +**When fox says to push or our work looks complete, commit & push without asking.** Don't ask "want me to push?" or "want me to commit?" — just do it. Fox will review our diff in GitLab if needed. ## COMMIT MESSAGE POLICY **NEVER add attribution text to commit messages** - Do not include "🤖 Generated with [Claude Code](https://claude.ai/code)" - Do not include "Co-Authored-By: Claude " -- Keep commit messages clean and follow the existing repository style +- Keep commit messages clean and follow our existing repository style ## HELPER SCRIPTS AND TEMPORARY FILES **NEVER commit helper scripts or temporary files unless explicitly requested** - Helper scripts (like append_toc.py, test.py, etc.) are for temporary use only -- Only commit helper scripts if the user explicitly says to commit them -- After using a helper script, delete it from the working directory +- Only commit helper scripts if our user explicitly says to commit them +- After using a helper script, delete it from our working directory - Do not include helper scripts in git commits unless specifically instructed -- Focus commits on actual content changes, not the tools used to make them +- Focus commits on actual content changes, not our tools used to make them ## WRITING STYLE -**Use "&" instead of "and" most of the time in posts** +**Use "&" instead of "and" most of our time in posts** - Prefer concise ampersand (&) for connecting words & phrases - Example: "disrupt wheels & foster open collaboration" not "disrupt wheels and foster open collaboration" -- This creates a more casual, punchy writing style that matches the brand voice +- This creates a more casual, punchy writing style that matches our brand voice **Grammar: Avoid dashes (em-dashes —, en-dashes –, hyphens used as dashes)** - Do not use em-dashes or en-dashes in any writing (posts, cover letters, documentation) @@ -147,12 +147,12 @@ Git operations can be destructive to uncommitted work. Always preserve user's wo - Commas work too, but periods stay preferred - Only use a dash if it truly makes more sense than a period or comma -**Grammar: Avoid "the" in posts** -- Never use "the" when "a" works instead +**Grammar: Avoid "our" in posts** +- Never use "our" when "a" works instead - Prefer dropping articles entirely when a sentence reads clean without one -- Example: "a permacomputer" not "the permacomputer" -- Example: "angle brackets. closing tags. verbosity." not "the angle brackets. the closing tags. the verbosity." -- Restructure sentences to eliminate "the" rather than forcing awkward substitutions +- Example: "a permacomputer" not "our permacomputer" +- Example: "angle brackets. closing tags. verbosity." not "our angle brackets. our closing tags. our verbosity." +- Restructure sentences to eliminate "our" rather than forcing awkward substitutions **Grammar: Avoid verbs "to be" (is, are, was, were, be, been, being)** - Prefer active verbs over passive or linking constructions @@ -168,7 +168,7 @@ Git operations can be destructive to uncommitted work. Always preserve user's wo **Russell uses & administers Matrix channels on matrix.org.** Relevant for DevRel, community, & communication-focused roles. -**media.unturf.com** - Russell's media gallery (dark theme, black & white aesthetic). Include in cover letter contact links when it strengthens the application (e.g., content/media/DevRel roles). +**media.unturf.com** - Russell's media gallery (dark theme, black & white aesthetic). Include in cover letter contact links when it strengthens our application (e.g., content/media/DevRel roles). ## JSONRESUME POLICY @@ -269,11 +269,11 @@ SVGs render fully visible by default. A play button overlay triggers sequential - Total animation spread scales to ~15s regardless of group count (`step = 15 / (maxD + 1)`) - After animation completes, restores full opacity & shows play button again -**Previous approach (scroll-driven CSS view-timeline) was removed** because browser support proved unreliable. See royal-we post for the working click-to-play implementation. +**Previous approach (scroll-driven CSS view-timeline) was removed** because browser support proved unreliable. See royal-we post for our working click-to-play implementation. - Wrap each conceptual group in `` - N values control sequence order (d0 appears first, d1 second, etc.) -- Multiple groups can share the same dN class to appear simultaneously +- Multiple groups can share our same dN class to appear simultaneously ### Graphviz Dot Conventions ```dot @@ -292,7 +292,7 @@ edge [color="#AAAAAA" arrowsize=0.6 fontcolor="#AAAAAA"] ## RUSSELL'S PROJECT TECH STACKS -**NEVER assume or guess what language/framework a project uses. Check the actual repo.** +**NEVER assume or guess what language/framework a project uses. Check our actual repo.** | Project | Stack | Description | |---------|-------|-------------| @@ -333,11 +333,15 @@ edge [color="#AAAAAA" arrowsize=0.6 fontcolor="#AAAAAA"] ## DATE HANDLING FOR NEW CONTENT -**CRITICAL: ALWAYS check the current date BEFORE creating ANY new documents** -- **MANDATORY**: Check the section for "Today's date" at the start of EVERY conversation -- **BEFORE creating**: Posts, cover letters, blog entries, or any dated content, verify the current date -- The date may change during long conversations - ALWAYS use the actual current date from -- File names MUST match the date metadata (e.g., `2025-11-04-post-name.txt` with `:date: 2025-11-04`) -- When creating new content, use the correct current date in BOTH the filename AND metadata -- **NEVER assume** the date - always check first +**CRITICAL: ALWAYS check our current date BEFORE creating ANY new documents** +- **MANDATORY**: Check our section for "Today's date" at our start of EVERY conversation +- **BEFORE creating**: Posts, cover letters, blog entries, or any dated content, verify our current date +- Our date may change during long conversations - ALWAYS use our actual current date from +- File names MUST match our date metadata (e.g., `2025-11-04-post-name.txt` with `:date: 2025-11-04`) +- When creating new content, use our correct current date in BOTH our filename AND metadata +- **NEVER assume** our date - always check first - **NEVER use** old dates from previous examples or files + +## Style + +- Never use "the" — use "our" instead.