Skip to main content

User Troubleshooting Guide

Quick solutions for common issues when using CODITECT framework.

Prerequisites​

Before troubleshooting, ensure you have:

  • CODITECT environment set up - Completed initial onboarding
  • Terminal access - Ability to run bash commands
  • Virtual environment available - .venv directory exists
  • Basic git knowledge - For submodule-related issues

Verify basic setup:

ls .venv/bin/activate   # Virtual environment exists
ls .coditect            # CODITECT link exists
git status              # Git working

Quick Start​

Diagnose most issues in 3 steps:

Step 1: Run Diagnostics​

# Quick health check
source .venv/bin/activate
./scripts/init.sh
python3 scripts/test-suite.py --quick

Step 2: Check Common Causes​

# Verify component activation
python3 scripts/update-component-activation.py list --activated-only | head -10

# Check symlinks
ls -la .coditect .claude

# Verify git status
git submodule status | head -5

Step 3: Apply Solution​

Find your specific issue in the sections below and follow the solution steps.

Component Issues​

Agent Not Found​

Symptom: Claude reports "agent not found" or doesn't recognize agent name.

Solutions:

  1. Check agent exists: ls agents/ | grep NAME
  2. Verify activation: python3 scripts/update-component-activation.py status agent NAME
  3. Activate if needed: python3 scripts/update-component-activation.py activate agent NAME

Command Not Working​

Symptom: Slash command doesn't execute or returns error.

Solutions:

  1. Check command exists: ls commands/NAME.md
  2. Verify command syntax in the markdown file
  3. Check if command requires specific arguments
  4. Ensure Claude Code CLI is up to date

Skill Not Loading​

Symptom: Skill pattern not applied correctly.

Solutions:

  1. Verify skill path: ls skills/NAME/SKILL.md
  2. Check for nested skills: find skills -name "SKILL.md"
  3. Ensure skill is activated in component-activation-status.json

Context Memory Issues​

/cx Not Finding Sessions​

Symptom: Context extraction finds 0 new messages.

Solutions:

  1. Check JSONL location: ls ~/.claude/projects/
  2. Verify file sizes: ls -lh ~/.claude/projects/*.jsonl | head
  3. Use min-size filter: /cx --min-size 1
  4. Check for exports: find . -name "*.txt" -path "*/EXPORT*"

/cxq Search Returns Empty​

Symptom: Context query returns no results.

Solutions:

  1. Run extraction first: /cx
  2. Check database exists: ls context-storage/sessions.db # ADR-118 Tier 3
  3. Verify index: /cxq --knowledge-stats
  4. Try broader search terms

Context Database Corrupted​

Symptom: SQLite errors when querying.

Solutions:

  1. Check backup: ./scripts/backup-context-db.sh --status
  2. Restore from backup: ./scripts/backup-context-db.sh --restore latest
  3. Re-extract if needed: rm context-storage/sessions.db && /cx # ADR-118

Git Issues​

Submodule Detached HEAD​

Symptom: Submodule shows "detached HEAD" after update.

Solutions:

cd submodules/affected-submodule
git checkout main
git pull
cd ../..
git add submodules/affected-submodule
git commit -m "Fix detached HEAD"

Git Sync Fails​

Symptom: /git-sync reports errors.

Solutions:

  1. Check git status: git status
  2. Resolve conflicts manually
  3. Run in analyze mode first: /git-sync --mode analyze
  4. Check remote access: git remote -v

Commit Hook Failures​

Symptom: Pre-commit hooks block commit.

Solutions:

  1. Check hook output for specific error
  2. Run linting: npx markdownlint-cli2 "**/*.md"
  3. Fix issues and retry
  4. Emergency bypass (if needed): git commit --no-verify (use sparingly)

Python Environment Issues​

Module Not Found​

Symptom: ModuleNotFoundError when running scripts.

Solutions:

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify Python path
which python  # Should show .venv/bin/python

Script Permission Denied​

Symptom: Permission denied when running scripts.

Solutions:

chmod +x scripts/script-name.sh
# Or run with Python directly:
python3 scripts/script-name.py

Performance Issues​

Slow Context Extraction​

Symptom: /cx takes very long.

Solutions:

  1. Use size filter: /cx --min-size 10 (only files >10MB)
  2. Skip indexing: /cx --no-index (faster, index later)
  3. Process single file: /cx specific-file.jsonl

Large Database Size​

Symptom: sessions.db exceeds 500MB.

Solutions:

  1. Backup first: ./scripts/backup-context-db.sh
  2. Consider archiving old messages
  3. Monitor growth: ls -lh context-storage/

Quick Diagnostic Commands​

# Check component counts
cat config/component-counts.json

# Verify symlinks
ls -la .coditect .claude

# Check git submodule status
git submodule status | head -10

# Verify Python environment
source .venv/bin/activate && python --version

# Check context database (ADR-118 Tier 3)
sqlite3 context-storage/sessions.db "SELECT COUNT(*) FROM messages;"

# Test agent activation
python3 scripts/update-component-activation.py list --activated-only | head -20

Getting Help​

  1. Search context: /cxq "error message"
  2. Check documentation: docs/ directory
  3. Review ADRs: internal/architecture/adrs/
  4. Report issues: https://github.com/coditect-ai/coditect-core/issues

Next Steps​

After resolving your issue:

  1. Document the solution - Use /cx "fixed [issue]" to capture the fix
  2. Prevent recurrence - Review USER-BEST-PRACTICES.md
  3. Check related issues - Run the full diagnostic suite
  4. Report if persistent - File issue at GitHub with reproduction steps
  5. Share knowledge - Add solution to context for future reference

Related guides:

Last Updated: 2025-12-22 Owner: AZ1.AI INC