Skill refresh

claude-code/skills/claude-memory/troubleshooting.md

@@ -0,0 +1,513 @@
+# Memory Troubleshooting Guide
+
+Detailed problem-solution reference for CLAUDE.md issues.
+
+## Problem 1: Memory File Not Loading
+
+**Symptoms**: Claude doesn't seem to remember project context, no awareness of CLAUDE.md contents.
+
+### Diagnosis
+
+```bash
+# Check if file exists
+ls -la CLAUDE.md
+ls -la .claude/CLAUDE.md
+ls -la ~/.claude/CLAUDE.md
+
+# Check file permissions
+ls -l CLAUDE.md
+
+# Check current directory
+pwd
+```
+
+### Common Causes & Solutions
+
+#### Cause 1: Wrong Location
+
+```bash
+# ❌ Bad: Random location
+/some/random/path/CLAUDE.md
+
+# ✓ Good: Project root
+./CLAUDE.md
+# or
+./.claude/CLAUDE.md
+```
+
+**Solution**: Move file to project root or `.claude/` directory.
+
+#### Cause 2: Wrong Filename (Case-Sensitive!)
+
+```bash
+# ❌ Bad
+claude.md
+Claude.md
+CLAUDE.MD
+README.md
+
+# ✓ Good
+CLAUDE.md
+```
+
+**Solution**: Rename to exactly `CLAUDE.md` (all caps).
+
+#### Cause 3: Syntax Errors in Imports
+
+```markdown
+# ❌ Bad: Broken import
+@docs/nonexistent.md
+
+# ✓ Good: Valid path
+@docs/architecture.md
+```
+
+**Solution**: Verify all imported paths exist and are correct.
+
+#### Cause 4: File Permissions
+
+```bash
+# Check permissions
+ls -l CLAUDE.md
+
+# If not readable, fix it
+chmod 644 CLAUDE.md
+```
+
+### Verification Test
+
+Add a temporary marker to CLAUDE.md:
+
+```markdown
+**MEMORY LOADED: This is a test marker**
+```
+
+Ask Claude: "What's the first line of your memory?"
+If Claude sees the marker, memory is loading correctly.
+Remove marker after test.
+
+---
+
+## Problem 2: Bloated Memory (Token Waste)
+
+**Symptoms**: Context fills up quickly, slow responses, high costs, frequent compaction.
+
+### Diagnosis
+
+```bash
+# Check file size
+wc -l CLAUDE.md
+# Goal: 100-200 lines max
+
+# Count characters (rough token estimate: chars ÷ 4)
+wc -c CLAUDE.md
+# Goal: < 20KB
+```
+
+### Solution: Trim and Split
+
+#### Before (Bloated - 500 lines)
+
+```markdown
+# Project Overview
+
+This project is a comprehensive e-commerce platform built with React, Node.js,
+Express, PostgreSQL, Redis, and Docker. The frontend uses React 18 with TypeScript
+in strict mode, Tailwind CSS for styling, React Router for navigation, Redux Toolkit
+for state management, and Axios for API calls. The backend uses Express.js with
+TypeScript, Sequelize ORM for database access, JWT for authentication, bcrypt for
+password hashing, and Redis for session management...
+
+[400 more lines of verbose content]
+```
+
+#### After (Lean - 150 lines)
+
+```markdown
+# Tech Stack
+
+- Frontend: React 18 + TypeScript + Tailwind
+- Backend: Express + PostgreSQL + Redis
+- Architecture: Microservices
+- Details: @docs/tech-stack.md
+
+## Common Commands
+
+```bash
+npm run dev    # Local development
+npm test       # Run all tests
+npm run build  # Production build
+```
+
+## Key Conventions
+
+- 2-space indentation
+- Functional components only
+- ESLint + Prettier
+- 80% test coverage minimum
+
+## IMPORTANT Rules
+
+- YOU MUST run tests before committing
+- Never commit .env files
+- Always update API docs when adding endpoints
+```
+
+**Result**: 70% token reduction
+
+### Compression Techniques
+
+1. **Use Bullet Points, Not Paragraphs**
+2. **Use Imports for Details**
+3. **Show Commands, Not Explanations**
+4. **Prefer Tables Over Text**
+
+---
+
+## Problem 3: Claude Not Following Instructions
+
+**Symptoms**: Claude ignores rules in CLAUDE.md, doesn't follow conventions.
+
+### Diagnosis
+
+Check instruction specificity:
+
+```markdown
+# ❌ Too Vague (ignored)
+- Write clean code
+- Follow best practices
+- Be careful with security
+
+# ✓ Specific (followed)
+- Use 2-space indentation (not tabs)
+- All API endpoints must have rate limiting
+- Hash passwords with bcrypt (min 10 rounds)
+```
+
+### Solution: Add Emphasis
+
+#### Weak Instruction (Often Ignored)
+
+```markdown
+Use functional components in React.
+Run tests before committing.
+```
+
+#### Strong Instruction (Followed)
+
+```markdown
+IMPORTANT: ALL React components MUST be functional (no class components).
+
+YOU MUST run `npm test` and ensure all tests pass before any git commit.
+```
+
+### Emphasis Hierarchy
+
+1. `ALL CAPS` - Maximum attention
+2. `IMPORTANT:` - Critical rules
+3. `YOU MUST` - Mandatory actions
+4. `NEVER` - Forbidden actions
+5. **Bold** - Standard emphasis
+6. Regular text - General info
+
+### Example: Strong Rules Section
+
+```markdown
+## IMPORTANT Project Rules
+
+YOU MUST:
+- Run full test suite before every commit
+- Get 2 PR approvals before merging
+- Update API documentation when adding endpoints
+
+NEVER:
+- Commit directly to main branch
+- Merge code with failing tests
+- Hardcode API keys or secrets
+
+ALWAYS:
+- Use environment variables for config
+- Include error handling in all async functions
+- Write tests for new features
+```
+
+---
+
+## Problem 4: Memory Updates Not Reflected
+
+**Symptoms**: Changes to CLAUDE.md don't take effect in current session.
+
+### Solutions
+
+#### Method 1: Quick Add (# Shortcut)
+
+```bash
+# At input prompt, press # first
+# Type: Use snake_case for Python functions
+# Claude auto-adds to appropriate CLAUDE.md
+```
+
+**Best For**: Quick single-line updates
+
+#### Method 2: /memory Command
+
+```bash
+/memory
+# Opens memory management interface
+```
+
+**Best For**: Reviewing and editing existing memory
+
+#### Method 3: Direct Edit + Reload
+
+```bash
+# Edit the file
+vim CLAUDE.md
+
+# Then explicitly ask Claude
+"Please re-read CLAUDE.md"
+```
+
+**Best For**: Major updates or reorganization
+
+#### Method 4: Session Restart (Most Reliable)
+
+```bash
+# Close and reopen Claude Code
+# Or Ctrl+C to exit CLI
+```
+
+**Best For**: When other methods don't work
+
+---
+
+## Problem 5: Too Many Memory Files
+
+**Symptoms**: Conflicting instructions, unclear hierarchy, unexpected behavior.
+
+### Diagnosis
+
+```bash
+# Find all CLAUDE.md files
+find . -name "CLAUDE.md"
+find ~ -name "CLAUDE.md"
+
+# Check which directory you're in
+pwd
+```
+
+### Understanding Priority
+
+Higher priority wins on conflicts:
+
+```
+1. ~/.claude/enterprise/CLAUDE.md  # Organization policy (highest)
+↓
+2. ./CLAUDE.md                     # Current project
+↓
+3. ~/.claude/CLAUDE.md             # Your personal defaults
+↓
+4. ./subfolder/CLAUDE.md           # Subfolder overrides
+```
+
+### Solution: Organize Properly
+
+#### Global Personal (~/.claude/CLAUDE.md)
+
+```markdown
+# Personal Defaults
+
+## Communication Style
+- Explain decisions before acting
+- Ask before destructive operations
+
+## Code Preferences
+- Prefer functional programming
+- Avoid premature optimization
+```
+
+**Use For**: Universal personal preferences
+
+#### Project Root (./CLAUDE.md)
+
+```markdown
+# MyProject
+
+@docs/tech-stack.md
+@docs/conventions.md
+
+IMPORTANT: This project uses OOP (override personal FP preference).
+
+Tech Stack: Java + Spring Boot
+```
+
+**Use For**: Project-specific standards (overrides personal)
+
+#### Subfolder (./frontend/CLAUDE.md)
+
+```markdown
+# Frontend Context
+
+- React 18 + TypeScript
+- Component structure: Atomic Design
+- See @../docs/ui-patterns.md
+```
+
+**Use For**: Directory-specific context (loaded when in that directory)
+
+---
+
+## Problem 6: Import Loops or Errors
+
+**Symptoms**: "Import depth exceeded", circular import error, or infinite loading.
+
+### Import Rules
+
+```markdown
+# ❌ Bad: Too Deep
+CLAUDE.md
+  → @docs/a.md (depth 1)
+    → @docs/b.md (depth 2)
+      → @docs/c.md (depth 3)
+        → @docs/d.md (depth 4)
+          → @docs/e.md (depth 5)
+            → @docs/f.md (depth 6 - FAILS!)
+
+# ✓ Good: Flat Structure
+CLAUDE.md
+  → @docs/architecture.md
+  → @docs/conventions.md
+  → @docs/testing.md
+  → @docs/deployment.md
+
+# ❌ Bad: Circular Import
+CLAUDE.md → @docs/a.md → @docs/b.md → @docs/a.md (LOOP!)
+
+# ✓ Good: No Circles
+CLAUDE.md → @docs/a.md → @docs/c.md
+         → @docs/b.md → @docs/c.md
+```
+
+### Solution: Restructure Imports
+
+**Before (Deep Chain)**:
+```markdown
+# CLAUDE.md
+@docs/main.md
+
+# docs/main.md
+@project/overview.md
+
+# project/overview.md
+@details/architecture.md
+
+# details/architecture.md
+[content]
+```
+
+**After (Flat)**:
+```markdown
+# CLAUDE.md
+@docs/overview.md
+@docs/architecture.md
+@docs/conventions.md
+```
+
+### Best Practices
+
+- **Max depth**: 5 levels
+- **No circular references**
+- **Prefer flat over deep**
+- **Use relative paths** for project files: `@docs/file.md`
+- **Use absolute paths** for global files: `@~/.claude/shared.md`
+
+---
+
+## Problem 7: Conflicting Team Instructions
+
+**Symptoms**: Different team members get different behavior from Claude.
+
+### Diagnosis
+
+```bash
+# Check for local overrides
+ls .claude/CLAUDE.local.md
+ls .claude/settings.local.json
+
+# Check git-tracked files
+git ls-files | grep -i claude
+```
+
+### Solution: Proper Separation
+
+#### Team-Shared (.claude/CLAUDE.md - in git)
+
+```markdown
+# Team Standards
+
+IMPORTANT: All team members follow these conventions.
+
+## Git Workflow
+1. Branch from `develop`
+2. PR requires 2 approvals
+3. Squash merge
+
+## Coding Standards
+@docs/style-guide.md
+
+## NEVER
+- Commit directly to main
+- Merge without tests
+```
+
+#### Personal (.claude/CLAUDE.local.md - gitignored)
+
+```markdown
+# My Personal Preferences
+
+[Individual customizations that don't affect team]
+```
+
+#### .gitignore Setup
+
+```gitignore
+# Personal files (not shared)
+.claude/CLAUDE.local.md
+.claude/settings.local.json
+```
+
+---
+
+## Quick Reference: Diagnostic Checklist
+
+When memory isn't working, check:
+
+```markdown
+- [ ] File named exactly "CLAUDE.md" (case-sensitive)
+- [ ] File in project root or .claude/ directory
+- [ ] File has read permissions (chmod 644)
+- [ ] Valid markdown syntax
+- [ ] Imports use correct paths
+- [ ] No circular import loops
+- [ ] Import depth ≤ 5 levels
+- [ ] File size < 20KB (~200 lines)
+- [ ] Instructions are specific, not vague
+- [ ] Used emphasis for critical rules
+- [ ] No syntax errors in code blocks
+- [ ] Tried session restart
+- [ ] Verified loading with test marker
+```
+
+---
+
+## Getting Help
+
+If problems persist:
+
+1. **Verify File Loading**: Add test marker, ask Claude to read it
+2. **Check Hierarchy**: Understand which files are being loaded
+3. **Review Syntax**: Ensure valid markdown and imports
+4. **Simplify First**: Start with minimal CLAUDE.md, add back gradually
+5. **Restart Session**: Most reliable way to reload changes
+
+For further assistance, see [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory).