Chatsubo MUD Development Blog

Pattern Documentation (CLAUDE_CONTEXT/)

Purpose: Maintain reusable implementation patterns to avoid repeating mistakes and rediscovering solutions.

When to create:

• After successfully implementing a feature (e.g., “overriding a default command”, “creating a room build script”)
• One markdown file per distinct pattern or feature type
• Store in CLAUDE_CONTEXT/ directory

Workflow:

1. Before implementing: Check existing CLAUDE_CONTEXT/ files for similar patterns
2. After success: Ask permission to document the pattern (specify filename)
3. When updated: Ask permission to update existing documents when understanding evolves

Pattern document should include:

• What problem it solves
• Working code examples
• Key insights that made it work
• Common mistakes to avoid
• References to actual implementation files

Cross-reference: When encountering recurring problems, see “Common Problems Registry” below

Common Problems Registry (CLAUDE_CONTEXT/PROBLEMS.md)

Purpose: Track recurring issues that appear across multiple implementation sessions.

When to add entries:

• Same problem encountered 2+ times in different contexts
• Examples: “Command vs MuxCommand”, “inventory override not working”, “content loader 2-part vs 3-part IDs”

Entry format:

### Problem: [Brief Description]
**Symptoms:** What the user sees / error messages
**Root Cause:** Why it happens
**Solution:** Reference to pattern document in CLAUDE_CONTEXT/
**Last Encountered:** [Date or commit hash]

Workflow:

• Check PROBLEMS.md when encountering unexpected behavior
• Ask permission before adding new problem entries
• Reference relevant pattern documentation files for solutions

Reference Check Protocol

Before implementing any feature:

1. Check CLAUDE_CONTEXT/PROBLEMS.md for known issues related to the task
2. Search CLAUDE_CONTEXT/ for pattern files matching the feature type
3. Review referenced pattern documents before writing code
4. If no pattern exists but task is non-trivial, ask if user wants pattern documented after success

This protocol helps avoid:

• Repeating solved problems
• Rediscovering working patterns through trial-and-error
• Making the same mistakes in new contexts

Root Cause Analysis Protocol

CRITICAL - Fix Root Causes, Not Symptoms:

• Always identify and fix the underlying root cause of a problem, not just the visible symptom
• Manual command fixes are temporary Band-Aids that mask the real issue
• Every fix should work automatically when the system runs normally - no human intervention required
• Ask “Why did this happen?” repeatedly until you find the systemic issue

Examples of symptom fixes to AVOID:

• Running manual commands to clean up state instead of preventing bad state
• Restarting services to clear errors instead of fixing what causes them
• Manually creating missing data instead of ensuring initialization code works
• Adding workarounds that need to be repeated every time the problem occurs

Examples of root cause fixes to PURSUE:

• Modify initialization code so required data is always created correctly
• Fix the logic that creates bad state in the first place
• Update automated processes (spawn managers, build scripts, migrations) to handle edge cases
• Add validation and error handling that prevents problems before they occur

Implementation approach:

1. When encountering a problem, investigate WHY it happened, not just WHAT is broken
2. Trace the issue back to its source in the automated systems
3. Fix the automated system so the problem cannot recur
4. Verify the fix works when the system runs without manual intervention
5. Document the root cause in pattern files if it’s likely to appear elsewhere

The test of a good fix:

• If the system is rebuilt/restarted from scratch, does everything work without manual commands?
• If automated processes run (respawn, spawn managers, build scripts), do they handle this case?
• Will another developer encounter this same issue in 6 months, or is it permanently solved?

Git Commit Message Format

DO NOT include emoji or “Generated with Claude Code” attribution in commit messages. Use clean, professional commit messages without decorative elements:

• NO emoji (, , etc.)
• NO “Generated with [Claude Code]” footer
• NO “Co-Authored-By: Claude” lines
• Use conventional commit format: <type>(<scope>): <description>
• Types: feat, fix, docs, style, refactor, perf, test, chore, security
• Scope examples: admin, quest, tutorial, bar, ui, discord
• Use imperative, present tense in description
• Don’t capitalize first letter of description
• No period at the end
• CRITICAL: Always check git diff --staged before committing to verify actual changes match commit message

Code Standards

File Content Standards

• NEVER use emojis in any files created or modified
• Use plain text alternatives for visual indicators
• Maintain professional, clean formatting without decorative characters
• Use text-based status indicators (e.g., “[PASS]”, “WARNING:”, “ERROR:”) instead of emoji symbols

Documentation Standards

1. Documentation Organization:
   • Place ALL documentation files in the ../chatsubo-docs/ folder (separate repository)
   • NEVER use docs/ folder inside chatsubo-mud - it is not used
   • Documentation repository is at: /data/docker/chatsubo-dev/chatsubo-docs/
   • Exception: Files required by GitHub conventions (README.md, CONTRIBUTING.md, LICENSE, .github/)
   • Never create documentation files in root unless they are GitHub-standard files
2. Large System Documentation Structure:
   • For complex systems (3+ related files), create dedicated folders under ../chatsubo-docs/
   • Example: ../chatsubo-docs/Discord Integration/ for all Discord-related documentation
   • Each system folder MUST include a README.md as navigation hub
   • Use descriptive folder names with proper capitalization
3. Testing Documentation Requirements:
   • ALL major systems MUST include a TESTING.md file in their documentation folder
   • TESTING.md should provide clear instructions for play testers
   • Include: what to test, how to test it, expected behaviors, known issues
   • Write for non-technical users who will be testing the system
   • Example: ../chatsubo-docs/Help System/TESTING.md for the help ticket system
4. Code Documentation:
   • Write clear docstrings for all classes and methods
   • Document public APIs and complex logic
   • Include usage examples in docstrings
   • Explain non-obvious implementation details

Question Response Protocol

CRITICAL - Questions Require Answers, Not Code Changes:

• When a user asks a question, provide a detailed answer explaining the current state
• Include analysis of why things work the way they do
• Offer recommendations and suggestions if appropriate
• NEVER automatically make code changes based on a question alone
• Always ask for explicit permission before making any modifications
• Questions are requests for information and understanding, not implementation requests

Recommendations and Analysis Protocol

CRITICAL - Lead with Your Best Thinking:

• When asked for a plan, proposal, or recommendations, provide your BEST and MOST COMPLETE analysis upfront
• Do not hold back better ideas or pivots “for later” - include them in the initial response
• Clearly mark which recommendations are essential vs. optional vs. nice-to-have
• Trust the user to push back or simplify if something is too complex or unnecessary
• DO NOT present a minimal/safe version and wait for the user to ask “any other recommendations?”
• The user’s time is valuable - they should not have to interrogate you to extract good ideas
• Present: Complete analysis → User decides what to keep/cut/modify → Execute
• NOT: Basic idea → User asks for more → Reveal what you held back → Repeat

Shell Command Overrides

• ALWAYS use \cd instead of cd (third-party override interferes with normal cd)