Refinement for context size

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

@@ -0,0 +1,235 @@
+# Troubleshooting Slash Commands
+
+Common problems and solutions.
+
+## Command Not Found
+
+**Symptoms**: `/mycommand` shows "Command not found"
+
+**Solutions**:
+1. Verify file exists in `.claude/commands/` directory
+2. Check filename ends with `.md` extension
+3. Ensure filename matches command name (dash-separated)
+4. Restart Claude Code to reload commands
+
+**Example**:
+```bash
+# Wrong location
+./commands/review.md
+
+# Correct location
+./.claude/commands/review.md
+
+# Usage
+/review @file.js
+```
+
+## Arguments Not Working
+
+**Symptoms**: Variables like `$ARGUMENTS` appear literally in output
+
+**Solutions**:
+1. Use correct syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`)
+2. Don't escape dollar signs in command files
+3. Verify arguments are passed when invoking command
+
+**Example**:
+```markdown
+# ❌ Wrong
+Review these files: ${ARGUMENTS}
+
+# ✓ Correct
+Review these files: $ARGUMENTS
+```
+
+## Bash Commands Not Executing
+
+**Symptoms**: `!git status` appears as text instead of executing
+
+**Solutions**:
+1. Add `allowed-tools` frontmatter with Bash specification
+2. Use specific patterns, not wildcard `*` unless necessary
+3. Ensure bash command is valid and available
+
+**Example**:
+```markdown
+---
+description: Git workflow
+allowed-tools: Bash(git status:*), Bash(git diff:*)
+---
+
+!git status
+!git diff --stat
+```
+
+## File References Not Loading
+
+**Symptoms**: `@file.js` doesn't load file content
+
+**Solutions**:
+1. Use `@` prefix before file path
+2. Verify file path is correct (relative to project root)
+3. Check file exists and is readable
+4. Combine with positional arguments: `@$1`
+
+**Example**:
+```markdown
+# Direct reference
+Review @src/main.js for issues
+
+# With argument
+Review @$1 for issues
+
+# Usage: /review src/main.js
+```
+
+## Permission Errors
+
+**Symptoms**: "Tool not allowed" or permission denied errors
+
+**Solutions**:
+1. Add required tools to `allowed-tools` frontmatter
+2. Use specific patterns instead of broad permissions
+3. Separate file paths from command patterns
+
+**Example**:
+```yaml
+# ✓ Good - specific permissions
+allowed-tools: Read(src/**), Bash(git status:*), Bash(git diff:*)
+
+# ⚠️ Risky - too permissive
+allowed-tools: *
+```
+
+## Command Timeout
+
+**Symptoms**: Command hangs or times out
+
+**Solutions**:
+1. Avoid long-running processes in `!` commands
+2. Use background processes if needed
+3. Break into smaller commands
+4. Consider using subagents for complex workflows
+
+## Model Not Respecting Instructions
+
+**Symptoms**: Claude doesn't follow command template
+
+**Solutions**:
+1. Use clear, imperative language
+2. Number steps explicitly
+3. Add constraints section
+4. Use `model: claude-sonnet-4` for complex commands
+
+**Example**:
+```markdown
+Review $ARGUMENTS
+
+YOU MUST:
+1. Check for X
+2. Verify Y
+3. Report Z
+
+DO NOT:
+- Skip any files
+- Suggest changes without explanation
+```
+
+## Description Not Showing in /help
+
+**Symptoms**: Command appears but no description
+
+**Solutions**:
+1. Verify frontmatter has `description` field
+2. Check YAML syntax (no tabs, proper spacing)
+3. Keep description under 100 characters for /help display
+
+**Example**:
+```yaml
+---
+description: Review code for security issues
+---
+```
+
+## Argument Hints Not Working
+
+**Symptoms**: Autocomplete doesn't show expected arguments
+
+**Solutions**:
+1. Add `argument-hint` to frontmatter
+2. Use standard format: `<arg1> <arg2>`
+3. Use descriptive names
+
+**Example**:
+```yaml
+---
+description: Generate tests
+argument-hint: <file-path> <function-name>
+---
+```
+
+## Commands Conflict with Built-ins
+
+**Symptoms**: Custom command doesn't run, built-in does instead
+
+**Solutions**:
+1. Use different command name
+2. Avoid names like `/help`, `/clear`, `/init`
+3. Use descriptive, unique names
+
+## Debugging Tips
+
+### Test Basic Structure
+```bash
+# Create minimal test command
+cat > .claude/commands/test.md << 'EOF'
+---
+description: Test command
+---
+
+Echo test: $ARGUMENTS
+EOF
+
+# Try it
+/test hello world
+# Should output: Echo test: hello world
+```
+
+### Test Bash Execution
+```markdown
+---
+description: Test bash
+allowed-tools: Bash(echo:*)
+---
+
+!echo "Bash works"
+
+Result above should show "Bash works"
+```
+
+### Test File Loading
+```markdown
+---
+description: Test file loading
+---
+
+Content from @package.json
+
+Above should show package.json content
+```
+
+### Verify Command Registration
+```bash
+# List all commands
+/help
+
+# Look for your command in the list
+```
+
+## Getting Help
+
+If problems persist:
+1. Check [Official Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
+2. Review command file syntax carefully
+3. Test with minimal example first
+4. Verify Claude Code version supports features