russell.ballestrini.net/CLAUDE.md

Claude Memory and Instructions

Read README.rst to understand the build system.

you are acting on behalf of russell ballestrini. don't fuck up.

CRITICAL PELICAN TESTING WORKFLOW

BEFORE ANY COMMIT:

1. ALWAYS test Pelican build: make clean && make html
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

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
• Invalid slugs/filenames cause issues

PROPER DEVELOPMENT WORKFLOW:

# Setup virtual environment (once)
make venv

# Test changes before commit
make clean && make html && make serve

# Check localhost:8000 for issues
# Only commit if build succeeds
git add specific-files
git commit -m "message"
git push

CRITICAL CONTENT DIRECTORY ISSUE

PROBLEM: Python virtual environments exist in content/uploads/2024/battleship-solvers/env/ and env2/

• These contain thousands of Python package files (.md, .rst files)
• Pelican tries to process them as blog content
• Causes massive build warnings and errors
• Should NOT be in content directory

SOLUTION NEEDED:

• Remove env/ and env2/ directories from content/uploads/
• Add env*/ to .gitignore patterns
• Keep only actual blog assets in content/uploads/

CRITICAL GIT SAFETY LESSON

DEVASTATING MISTAKE COMMITTED:

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
3. Result: User's uncommitted translation work was completely lost/overwritten

PROPER APPROACH:

• ALWAYS check git status and git diff first to see what uncommitted work exists
• NEVER use git add . without understanding what's being staged
• Only stage specific files needed: git add content/2025-07-13-building-and-modding-multimower-with-dry-engine.rst
• If I need to unstage, use git restore --staged <file> for specific files, NOT git reset HEAD .

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.

COMMIT MESSAGE POLICY

NEVER add attribution text to commit messages

• Do not include "🤖 Generated with Claude Code"
• Do not include "Co-Authored-By: Claude noreply@anthropic.com"
• Keep commit messages clean and follow the 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
• Do not include helper scripts in git commits unless specifically instructed
• Focus commits on actual content changes, not the tools used to make them

WRITING STYLE

Use "&" instead of "and" most of the 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

Grammar: Don't overuse em-dashes (—) in place of commas

• Em-dashes are useful for emphasis or parenthetical thoughts, but overuse makes writing choppy
• If a sentence has multiple "—" breaks, consider using commas or splitting into separate sentences
• Example of overuse: "The opportunity to work—learning from experienced operators while contributing—combines technical challenge"
• Better: "The opportunity to work with experienced operators while contributing combines technical challenge"
• Use em-dashes sparingly for maximum impact

DATE HANDLING FOR NEW CONTENT

ALWAYS check the current date before creating new posts or cover letters

• Check the section for "Today's date" at the start of the conversation
• The date may change during long conversations - use the actual current date
• File names should 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