ML Odyssey - Claude Coding Rules

# ML Odyssey - Claude Coding Rules

> **Note**: For comprehensive project documentation, workflows, and conventions, see [CLAUDE.md](CLAUDE.md).
> This file contains quick reference templates and troubleshooting tips.

## Code Templates

### Shell Scripts

```bash
#!/bin/bash
# Script description
# Usage: script_name.sh [options]

set -e  # Exit on error
set -u  # Error on undefined variables
set -o pipefail  # Catch errors in pipelines

# Script implementation here
```

### Mojo Code

```mojo
# Mojo implementation template
# Follow Mojo best practices from CLAUDE.md

from memory import memset_zero
from sys.info import simdwidthof

fn performance_critical_function[T: DType](inout data: Tensor[T]) -> None:
    """Performance-critical function using fn.

    Args:
        data: Input tensor to process in-place.
    """
    # Use SIMD operations for performance
    alias simd_width = simdwidthof[T]()
    # Implementation here
    pass

def prototype_function(data: object) -> object:
    """Prototype function using def for flexibility.

    Args:
        data: Input data (flexible typing during prototyping).

    Returns:
        Processed data.
    """
    # Implementation here
    return data

struct TypeSafeStruct:
    """Use struct for type safety and performance."""
    var field: Int

    fn __init__(inout self, value: Int):
        self.field = value
```

**Mojo Best Practices**:

- Use `fn` for performance-critical code (compile-time optimizations)
- Use `def` for prototyping and flexibility
- Leverage SIMD operations for parallel processing
- Always include type annotations
- All code must pass `pixi run mojo format` before committing (enforced by pixi run pre-commit hooks)

## Quick Troubleshooting

### GitHub CLI Issues

```bash
# Authentication problems
gh auth status
gh auth refresh -h github.com

# Issue creation fails
gh auth status  # Check authentication
gh issue list   # Verify repo access
```

### Script Errors

```bash
# Python version check
python3 --version  # Requires 3.7+

# Check logs
tail -100 logs/create_issues_*.log

# Test without creating issues
python3 scripts/create_issues.py --dry-run
```

### Pre-commit Hook Failures

```bash
# Run hooks manually
just pre-commit-all

# Mojo format issues
pixi run mojo format path/to/file.mojo

# Markdown linting issues
npx markdownlint-cli2 path/to/file.md

# NEVER use --no-verify - Fix hook failures instead
# If specific hook is broken: SKIP=hook-name git commit
```

### Common Errors

**"GitHub issue not found"**:

- Verify issue exists: `gh issue view <number>`
- Check authentication: `gh auth status`

**"Mojo format fails"**:

- Ensure Pixi environment is active
- Run: `pixi run mojo format file.mojo`
- Check syntax errors in Mojo code

**"GitHub issue creation fails"**:

- Check auth: `gh auth status`
- Verify repo access: `gh repo view`
- Check issue body is valid markdown

## See Also

- [CLAUDE.md](CLAUDE.md) - Comprehensive project documentation
- [README.md](README.md) - Main project README
- [scripts/README.md](scripts/README.md) - Scripts documentation
- [agents/README.md](agents/README.md) - Agent system documentation
- [notes/review/](notes/review/) - Architectural decisions and comprehensive specs

## Agent Hub

.claude/ is the centralized location for agentic descriptions and SKILLs. Sub-agents reference `.claude/agents/*.md` and `.claude/skills/*.md` for roles, capabilities, and prod fix learnings.