ClaudeForge/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for ClaudeForge.

---

Installation Issues

Issue: Command not recognized after installation

Symptoms:

• /enhance-claude-md shows "command not found"
• Slash command doesn't autocomplete

Causes:

• Claude Code hasn't reloaded components
• Incorrect installation path
• Insufficient permissions

Solutions:

1. Restart Claude Code completely:

   # Quit Claude Code entirely (not just close window)
   # Reopen Claude Code
   # Wait 5-10 seconds for components to load
   

2. Verify installation paths:

   # macOS/Linux
   ls -la ~/.claude/commands/enhance-claude-md.md ~/.claude/commands/sync-claude-md.md
   ls -la ~/.claude/skills/claudeforge-skill/
   ls -la ~/.claude/agents/claude-md-guardian.md
   
   # Windows
   dir %USERPROFILE%\.claude\commands\enhance-claude-md\
   dir %USERPROFILE%\.claude\skills\claudeforge-skill\
   dir %USERPROFILE%\.claude\agents\claude-md-guardian.md
   

3. Reinstall with correct permissions:

   chmod +x install.sh  # macOS/Linux
   ./install.sh
   

---

Issue: "Skill not found" error

Symptoms:

• Error message: "claude-md-enhancer skill not found"
• Slash command runs but fails

Cause: Skill directory name mismatch or missing skill files

Solutions:

1. Check skill directory name (must be exact):

   ls ~/.claude/skills/
   # Must show: claudeforge-skill
   

2. Verify skill files exist:

   ls ~/.claude/skills/claudeforge-skill/
   # Must contain: SKILL.md, analyzer.py, generator.py, etc.
   

3. Reinstall skill only:

   rm -rf ~/.claude/skills/claudeforge-skill
   cp -r skill ~/.claude/skills/claudeforge-skill
   

---

Issue: Windows PowerShell execution policy error

Symptoms:

• Error: "execution of scripts is disabled on this system"

Cause: PowerShell security settings

Solution:

# Run PowerShell as Administrator
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

---

Usage Issues

Issue: Quality score unexpectedly low

Symptoms:

• Quality score < 50
• Many "missing section" warnings

Causes:

• Basic CLAUDE.md without native format sections
• File too short (< 20 lines) or too long (> 400 lines)
• Missing required sections

Solutions:

1. Let ClaudeForge add missing sections:

   /enhance-claude-md
   # Claude will identify missing sections
   # Confirm enhancement
   # Quality score will improve
   

2. Check file length:

   wc -l CLAUDE.md
   # Hard cap: 150 lines. Sweet spot: 50-120.
   # If > 300: Consider modular architecture
   

3. Manually add required sections:

   • Core Principles
   • Tech Stack
   • Workflow Instructions
   • Project Structure (ASCII diagram)
   • Setup & Installation

---

Issue: Generated content too generic

Symptoms:

• CLAUDE.md doesn't mention specific tech stack
• No project-specific guidelines
• Feels like template without customization

Causes:

• Project detection failed (no package.json, requirements.txt, etc.)
• Insufficient project context

Solutions:

1. Provide explicit context:

   /enhance-claude-md
   
   # When Claude asks, specify:
   "This is a Python FastAPI microservice with PostgreSQL, Redis, and Docker. Team of 8 developers, MVP phase."
   

2. Add project files before running:

   # Ensure detection files exist:
   touch package.json      # Node.js
   touch requirements.txt  # Python
   touch go.mod            # Go
   touch Cargo.toml        # Rust
   

3. Manual customization after generation:

   • Edit generated CLAUDE.md
   • Add project-specific conventions
   • Include team standards

---

Issue: Modular architecture not recommended

Symptoms:

• Single CLAUDE.md generated for large project
• File exceeds the 150-line cap (validator hook will surface this)

Causes:

• Project type not detected as fullstack
• Team size estimated as small

Solutions:

1. Explicitly request modular:

   /enhance-claude-md
   
   # Tell Claude:
   "Use modular architecture with separate files for backend, frontend, and database"
   

2. Create backend/ and frontend/ directories:

   mkdir -p backend frontend
   # Then run /enhance-claude-md
   

3. Manual split if needed:

   # Create context files manually:
   touch backend/CLAUDE.md
   touch frontend/CLAUDE.md
   
   # Then run enhancement on each:
   cd backend && /enhance-claude-md
   cd frontend && /enhance-claude-md
   

---

Issue: Guardian agent not updating automatically

Symptoms:

• Made significant changes
• Started new session
• CLAUDE.md not updated

Causes:

• Agent not installed
• Changes below significance threshold
• Git repository not initialized

Solutions:

1. Verify agent installation:

   ls ~/.claude/agents/claude-md-guardian.md
   

2. Check git repository:

   git status
   # Agent requires git for change detection
   

3. Manually invoke agent:

   # In Claude Code:
   Claude, invoke claude-md-guardian to update CLAUDE.md
   

4. Lower significance threshold (if needed): Edit agent/claude-md-guardian.md:

   # Change from 5 to 3 files minimum
   - Less than 5 files modified  # Change to 3
   

---

Output Issues

Issue: CLAUDE.md missing Project Structure diagram

Symptoms:

• No ASCII tree diagram in output
• Native format incomplete

Cause: Template generation skipped structure section

Solution:

1. Regenerate with explicit request:

   /enhance-claude-md
   
   # Tell Claude:
   "Add Project Structure section with ASCII tree diagram"
   

2. Manual addition:

   ## Project Structure
   
   

   project/ ├── src/ │ ├── components/ │ └── services/ └── tests/

---

Issue: Setup & Installation section generic

Symptoms:

• Says "npm install" for Python project
• Incorrect commands

Cause: Tech stack detection mismatch

Solution:

1. Verify tech stack detection:

   # Check project files:
   ls package.json requirements.txt go.mod
   

2. Regenerate with correct context:

   /enhance-claude-md
   
   "This is a Python project, not Node.js"
   

3. Manual fix: Edit CLAUDE.md and correct commands

---

Performance Issues

Issue: Guardian agent too slow

Symptoms:

• Agent takes > 30 seconds
• Multiple updates in single session

Causes:

• Model set to sonnet instead of haiku
• Full regeneration instead of targeted update

Solutions:

1. Verify agent model:

   grep "model:" ~/.claude/agents/claude-md-guardian.md
   # Should be: model: haiku
   

2. Check agent workflow:

   • Should use targeted section updates
   • Not full file regeneration

---

Issue: Slash command timeout

Symptoms:

• Command starts but never completes
• "Timeout" error

Causes:

• Large repository exploration
• Network issues (if fetching remote content)

Solutions:

1. Run in smaller scope:

   cd specific-directory
   /enhance-claude-md
   

2. Skip exploration, provide context directly:

   /enhance-claude-md
   
   "Skip exploration. Create CLAUDE.md for TypeScript React app with PostgreSQL."
   

---

Integration Issues

Issue: Git commands fail in agent

Symptoms:

• Agent error: "git: command not found"
• Agent can't detect changes

Cause: Git not installed or not in PATH

Solutions:

1. Install git:

   # macOS
   brew install git
   
   # Ubuntu/Debian
   sudo apt-get install git
   
   # Windows
   # Download from git-scm.com
   

2. Verify git installation:

   git --version
   # Should show: git version 2.x
   

---

Issue: Quality hooks not working

Symptoms:

• Pre-commit hook doesn't run
• No validation before commit

Causes:

• Hook not executable
• Git not configured to use hooks
• Wrong hooks directory

Solutions:

1. Make hook executable:

   chmod +x .claude/hooks/pre-commit.sh
   

2. Configure git:

   git config core.hooksPath .claude/hooks
   

3. Test hook manually:

   ./.claude/hooks/pre-commit.sh
   # Should validate CLAUDE.md
   

---

Validation Errors

Issue: "File length exceeds recommended maximum"

Symptoms:

• Validation warning: File > 300 lines
• Quality score penalty

Cause: Single file too large

Solution:

1. Split into modular architecture:

   /enhance-claude-md
   
   "Convert to modular architecture with separate backend and frontend files"
   

2. Remove unnecessary content:

   • Delete redundant sections
   • Move detailed examples to separate docs
   • Link to external documentation

---

Issue: "Missing required sections"

Symptoms:

• Validation fails
• Lists missing: Core Principles, Tech Stack, etc.

Solution:

1. Let ClaudeForge add them:

   /enhance-claude-md
   # Claude will identify and add missing sections
   

2. Manual addition: Add required sections following native format

---

Common Error Messages

"CLAUDE.md not found"

Meaning: File doesn't exist (expected for new projects)

Action: Continue with initialization workflow

---

"Quality score: 0/100"

Meaning: Empty or invalid file

Action: Regenerate completely

---

"Invalid project structure"

Meaning: Cannot detect project type

Action: Add project files (package.json, etc.) or provide context manually

---

"Template selection failed"

Meaning: No matching template for project

Action: Provide more specific project context

---

Getting Help

If your issue isn't covered here:

1. Check GitHub Issues: https://github.com/alirezarezvani/ClaudeForge/issues

2. Search Discussions: https://github.com/alirezarezvani/ClaudeForge/discussions

3. Open New Issue:

   • Describe the problem
   • Include steps to reproduce
   • Attach relevant logs or errors
   • Mention your OS and Claude Code version

4. Review Documentation:

   • INSTALLATION.md
   • QUICK_START.md
   • ARCHITECTURE.md
   • CLAUDE.md

---

Debug Mode

To get more detailed output:

# Run installer with verbose output:
bash -x install.sh

# Check Claude Code logs:
# macOS: ~/Library/Logs/Claude Code/
# Linux: ~/.config/claude-code/logs/
# Windows: %APPDATA%\Claude Code\logs\

---

Still having issues? We're here to help!

Open an issue: https://github.com/alirezarezvani/ClaudeForge/issues/new