AI Context System

Appearance

Troubleshooting ​

Common issues and solutions for AI Context System v6.0.

Commands Not Working ​

Slash Commands Don't Execute ​

Symptoms:

  • Type /save and nothing happens
  • No command suggestions when typing /
  • Commands not recognized

Check:

bash
ls .claude/commands/
# Should show 8 files:
# init-context.md, save.md, update-context-system.md,
# review-security.md, review-performance.md,
# review-accessibility.md, review-seo.md, review-cost.md

Solution:

bash
# If missing, reinstall:
git clone --depth 1 https://github.com/rexkirshner/ai-context-system.git
cp -r ai-context-system/.claude/commands .claude/
cp ai-context-system/.claude/VERSION .claude/
rm -rf ai-context-system

# Then restart Claude Code session

Multiple .claude Directories ​

Symptoms:

  • Commands execute but affect wrong project
  • Context files appear in wrong location

Cause: Multiple .claude directories in parent folders.

Check:

bash
find ~ -name ".claude" -type d 2>/dev/null | head -20

Solution:

bash
# Remove .claude from parent directories
rm -rf /path/to/parent/.claude

# Keep only your project's .claude

Context Files ​

Missing Context Files ​

Symptoms:

  • context/STATUS.md doesn't exist
  • /save fails to update status

Solution:

bash
# Initialize context files
/init-context

This creates:

  • CLAUDE.md — Entry point (at project root)
  • context/STATUS.md — Current state
  • context/DECISIONS.md — Decision log

Context Files Exist But Wrong Format ​

Symptoms:

  • Files have v5.x format (SESSIONS.md, Quick Reference, etc.)
  • /save stops with "STATUS.md is in v5.x format" message

Cause: v6.0.2 added a format guard to prevent /save from corrupting v5.x context files.

Solution:

Run the migration script:

bash
curl -O https://raw.githubusercontent.com/rexkirshner/ai-context-system/main/migrate-to-v6.sh
chmod +x migrate-to-v6.sh
./migrate-to-v6.sh

Or manually update STATUS.md to v6.0 format:

markdown
# Status

SchemaVersion: 1
LastUpdated: YYYY-MM-DD
HeadCommit: [git SHA or N/A]
Objective: [current goal]

## Working Set

- [files you're touching]

## Next Actions

- [concrete next steps]

## Blocked On

- (None)

See Migration Guide for full details.

Git Integration ​

HeadCommit Shows N/A ​

Symptoms:

markdown
HeadCommit: N/A

Cause: Not a git repository, or running from subdirectory.

Check:

bash
git rev-parse --short HEAD

Solution:

  • If not a git repo, this is expected behavior
  • If git repo, ensure you're running from project root

HeadCommit Stale (Different from Current HEAD) ​

Symptoms:

  • STATUS.md shows HeadCommit: abc123
  • But git rev-parse --short HEAD shows def456

Cause: Commits were made outside the context system (by another tool, team member, or CI).

Solution: This is a warning that STATUS.md might be outdated. Review before continuing:

bash
# See what changed
git log abc123..HEAD --oneline

# Then update
/save

Installation Issues ​

Clone Fails ​

Symptoms:

fatal: could not create work tree dir

Check:

bash
# Verify you have write permission
ls -la .

# Check disk space
df -h

Solution:

  • Ensure you have write permissions to current directory
  • Free up disk space if needed

Commands Not Recognized After Install ​

Symptoms:

  • Files exist in .claude/commands/
  • But /save doesn't work

Solution:

bash
# Exit and restart Claude Code
exit
claude

Claude Code loads command definitions once per session. After installation, you need to start a new session.

Version Issues ​

Need to Update ​

Check current version:

bash
cat .claude/VERSION

Update to latest:

bash
/update-context-system

Or manually:

bash
git clone --depth 1 https://github.com/rexkirshner/ai-context-system.git
cp -r ai-context-system/.claude/commands .claude/
cp ai-context-system/.claude/VERSION .claude/
rm -rf ai-context-system

Migrating from v5.x ​

If you have v5.x installed (22 commands, agents, scripts), use the migration script:

bash
curl -O https://raw.githubusercontent.com/rexkirshner/ai-context-system/main/migrate-to-v6.sh
chmod +x migrate-to-v6.sh
./migrate-to-v6.sh

The /update-context-system command does not handle pre-v6 migrations.

See Migration Guide for full details.

"/update-context-system says I'm on pre-v6" ​

This is correct behavior. The command only handles v6.x → v6.y upgrades.

Use the migration script instead (see above).

"/save says STATUS.md is in v5.x format" ​

This is a format guard preventing corruption of v5.x context files.

See Context Files Exist But Wrong Format above for the solution.

"migrate-to-v6.sh says I'm already on v6.x" ​

Correct. You don't need the migration script. Use /update-context-system for v6.x → v6.y upgrades.

"migrate-to-v6.sh says no v5.x installation detected" ​

This means you don't have any v5.x artifacts. Either:

  • This is a fresh project — use /init-context to set up
  • You already migrated — use /update-context-system for future upgrades

Common Workflow Issues ​

Can't Resume After Break ​

Symptoms:

  • Don't know where to start
  • Last session unclear

Cause: Didn't run /save before break.

Prevention:

bash
# Always before breaks:
/save

Recovery:

bash
# Check git log for recent changes
git log --oneline -10

# Check file modification times
ls -lt src/

# Reconstruct and update STATUS.md manually

Lost Track of Working Set ​

Symptoms:

  • Working Set lists files you're no longer touching
  • Forgot to update it when focus shifted

Solution:

bash
# Update STATUS.md with current Working Set
/save

The /save command updates the Working Set based on the session's work.

Decisions Not Captured ​

Symptoms:

  • Made important decision yesterday
  • No record in DECISIONS.md

Note: /save now records decisions autonomously. If a decision wasn't captured, you can add it manually.

Manual entry: Add to context/DECISIONS.md:

markdown
---

## YYYY-MM-DD: [Area] Decision Title
Why: [reason for the decision]
Tradeoff: [what you gave up]
RevisitWhen: [trigger to revisit]

Emergency Recovery ​

Reinstall Everything ​

If system is broken:

bash
# 1. Backup context
cp -r context context-backup

# 2. Remove old installation
rm -rf .claude

# 3. Reinstall
git clone --depth 1 https://github.com/rexkirshner/ai-context-system.git
mkdir -p .claude
cp -r ai-context-system/.claude/commands .claude/
cp ai-context-system/.claude/VERSION .claude/
rm -rf ai-context-system

# 4. Restore context
mv context-backup/* context/

# 5. Restart Claude Code
exit
claude

Context Files Corrupted ​

If STATUS.md or DECISIONS.md are broken:

bash
# Check git history
git log context/STATUS.md
git checkout HEAD~1 context/STATUS.md

# Or recreate from template
/init-context
# (Will create new files, then merge in old content manually)

Getting Help ​

Documentation ​

GitHub ​

Reporting Bugs ​

Include:

  1. What you were trying to do
  2. What command you ran
  3. What error you got
  4. System info:
    bash
    cat .claude/VERSION
ls -la .claude/commands/
ls -la context/

Still Stuck? ​

If none of these solutions work:

  1. Check GitHub Issues
  2. File a new issue with details
  3. Ask in GitHub Discussions

Remember: When in doubt, /save!