uv-debug

# UV Debugging Skill

## Purpose

This skill provides systematic troubleshooting workflows for common `uv` (Python package manager) issues, with particular focus on build cache problems, installation discrepancies, and package update issues.

## When to Use This Skill

Use this skill when encountering:

- Code changes not appearing after `uv tool install`
- Discrepancy between `uv run <command>` and globally installed command
- New files/modules missing from installed package
- "Command not found" after installation
- Stale build cache issues
- Installation mode confusion (editable vs production)

## Core Concepts

### UV Installation Modes

**Production Install:**
```bash
uv tool install .
```
- Builds wheel package (cached snapshot)
- Fast to install, slow to update
- Requires reinstall after code changes
- Isolated from source directory

**Editable Install:**
```bash
uv tool install --editable .
```
- Creates symlinks to source directory
- Changes reflect immediately
- Best for active development
- Less isolated

**Local Environment:**
```bash
uv sync          # Setup environment
uv run <command> # Execute from source
```
- No global install needed
- Always uses current source code
- Fastest iteration cycle
- Recommended for development

### Build Cache Location

**Global tool installs:**
```
~/.local/share/uv/tools/<package-name>/
```

**Build artifacts:**
```
build/          - Temporary build files
dist/           - Built wheels (.whl) and source distributions
*.egg-info/     - Package metadata and file manifest
```

## Troubleshooting Workflows

### Workflow 1: Code Changes Not Appearing

**Symptoms:**
- Ran `uv tool install .` or `make install`
- Code changes don't appear in installed command
- New files/modules missing

**Diagnostic Steps:**

1. **Verify the discrepancy:**
   ```bash
   # Check which version is running
   which <command>

   # Test local version
   uv run <command> --help

   # Test global version
   <command> --help
   ```

2. **Check for s